好的，使用 Trea 编译器（一个结合了 Vue 前端和 Spring Boot 后端开发的工具或框架）进行项目开发时，制定清晰的项目规则至关重要。这能确保团队协作顺畅、代码风格统一、项目结构清晰。

以下是为您的 Vue + Spring Boot 全栈项目量身定制的一套项目规则，涵盖了目录结构、编码规范、API 设计、构建部署等多个方面。

Trea Vue + Spring Boot 全栈项目开发规则

一、 项目结构与命名规范

  1. 总体结构 (Monorepo 推荐)

    • 项目根目录下分为两个主要模块：bc-cxbs-frount/ 和 bc-cxbs-back/。
    • 使用一个 Git 仓库进行管理，便于关联性修改和版本控制。

  2. 后端 (Spring Boot) 规范

    • 包名(Package): 使用 com.[公司/组织名].[项目名].[模块名] 的格式。

      • 示例：com.xxx.xxx.controller, com.xxx.xxx.service.impl, com.xxx.xxx.mapper
    • 类名(Class): 大驼峰命名法 (UserService, EmployeeController)
    • 方法名(Method): 小驼峰命名法 (getUserById, createNewOrder)
    • 变量(Variable): 小驼峰命名法 (userName, orderList)
    • 常量(Constant): 全大写，下划线分割 (MAX_CONNECTION, DEFAULT_TIMEOUT)
  3. 前端 (Vue) 规范

二、 代码风格与质量

  1. 后端 (Spring Boot)

    • 代码格式化: 统一使用 Spotless 或 Google Java Format 插件，在提交代码时自动格式化。
    • 静态代码分析: 集成 SonarQube 或使用 Checkstyle, PMD 进行代码质量扫描。必须修复 Blocker 和 Critical 级别的漏洞。
    • 依赖管理: 在 pom.xml 中使用 <dependencyManagement> 统一管理依赖版本。

  2. 前端 (Vue)

    • 代码格式化: 统一使用 Prettier。
    • 代码检查: 统一使用 ESLint，推荐使用 @vue/eslint-config-prettier 规则集以避免与 Prettier 冲突。
    • 编辑器配置: 项目根目录提供 .editorconfig 文件，确保不同 IDE 基础格式一致。
    • Git Hook: 使用 Husky + lint-staged，在 git commit 前自动格式化代码 (prettier --write) 和进行 ESLint 检查。

三、 API 设计规范 (RESTful)

  1. 基本原则

    • 使用 HTTP 动词 (GET, POST, PUT, DELETE, PATCH) 表示操作类型。
    • 使用 名词复数 表示资源集合。
    • 返回合适的 HTTP 状态码 (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error)。

  2. URL 示例

    • GET /api/v1/users： 获取用户列表
    • POST /api/v1/users： 创建一个新用户
    • GET /api/v1/users/{id}： 获取单个用户详情
    • PUT /api/v1/users/{id}： 替换/更新一个用户（全量）
    • PATCH /api/v1/users/{id}： 部分更新一个用户
    • DELETE /api/v1/users/{id}： 删除一个用户

  3. 响应体格式

    • 统一使用 JSON 格式。
    • 响应体应包裹在一个标准的结构中，包含 code, data, message 等字段，便于前端统一处理。
    {
  "code": 200,
  "data": {
    "id": xxx,
    "name": "xxx"
  },
  "message": "Success"
}

    • 对于列表，应提供分页信息：

      {
"code": 1000,
"msg": null,
"pageNum": 1,
"pageSize": 10,
"total": 5,
"pages": 1,
"list": [
{
    "userId": xxx,
    "deptId": xxx
}
],
"hasPreviousPage": false,
"hasNextPage": false,
"firstPage": true,
"lastPage": true,
"empty": false,
"offset": 0
}

  4. API 文档

    • 后端必须使用 OpenAPI 3.0 (Swagger) 自动生成 API 文档。
    • 集成 springdoc-openapi 库，访问 /v3/api-docs 或 /swagger-ui.html 即可查看和调试接口。

四、 前后端交互与联调

  1. 环境配置

    • 前端使用 vue.config.js 的 devServer.proxy 配置开发环境代理，解决跨域问题。

      // vue.config.js
module.exports = {
  devServer: {
proxy: {
  '/api': {
    target: 'http://localhost:8080', // 后端本地地址
    changeOrigin: true
  }
}
  }
};

  2. Axios 封装

    • 前端统一封装 Axios 实例，设置基地址 (baseURL)、请求/响应拦截器。
    • 拦截器中统一处理错误（如弹出错误消息）、添加认证 Token 等。

  3. 状态管理 (Vue)

    • 中大型项目推荐使用 Pinia (Vuex 的升级版) 进行全局状态管理，管理用户信息、应用配置等跨组件数据。

五、 数据与安全

  1. 前端安全

    • 对用户输入进行校验和转义，防止 XSS。
    • 谨慎使用 v-html。

六、 构建与部署

  1. 环境分离

    • 为开发 (dev)、测试 (test)、生产 (prod) 环境提供不同的配置文件（如 application-dev.yml, .env.development, .env.production）。

  2. 后端构建

    • 使用 maven clean package -DskipTests 打包生成可执行的 JAR 文件。

  3. 前端构建

    • 使用 npm run build 生成静态资源文件 (dist 目录)。

  4. 部署策略 (示例)

    • 方案A (分离部署)： 前端静态文件部署到 Nginx 或对象存储 (AWS S3, OSS)。后端 JAR 包部署到服务器或容器中。Nginx 同时作为反向代理将 API 请求转发给后端服务。
    • 方案B (集成部署)： 将 npm run build 后的前端 dist 目录内容复制到 Spring Boot 的 src/main/resources/static/ 目录下，打包成一个 JAR。Spring Boot 同时提供 API 和静态资源服务。（适合简单项目）

如何使用这份规则：

  1. 将这份规则保存为 PROJECT_RULES.md 或 DEVELOPMENT_GUIDE.md 放在项目根目录。
  2. 让所有团队成员阅读并同意遵守。
  3. 将规则中的工具（Prettier, ESLint, Husky, Spotless, springdoc）具体配置到项目中。
  4. 在 Code Review 中严格检查这些规则的执行情况。

希望这套详细的规则能帮助您的 Trea 项目顺利开发！

标签: none

添加新评论