全栈项目团队开发规范？

访客全栈框架 2026-06-06 19:16:58 1

本文目录导读：

代码仓库与分支管理 (Git Flow)
技术栈统一与脚手架约定
项目结构与目录规范
前后端协作规范
编码与质量规范
开发流程与协作工具
总结：团队规范落地的 KEY POINTS

这是一份经过整理的全栈项目团队开发规范，涵盖了从代码管理、技术选型到协作流程的各个方面，这份规范旨在平衡开发效率与项目可维护性。

代码仓库与分支管理 (Git Flow)

选用一种适合团队规模的 Git 分支模型，推荐 Trunk-Based Development 或简化版 GitHub Flow。

分支约定 (以 GitHub Flow 为例)：
- main：主分支，代码必须经过 Code Review 和 CI 测试，禁止直接推送。
- feat/xxx：功能分支，从 main 拉出，开发完成后合回 main。
- fix/xxx：Bug 修复分支。
- release/vx.x.x：预发布分支（可选，用于版本发布前最后一次回归测试）。
- hotfix/xxx：紧急修复分支（直接从 main 拉出，修复后需同时合并到 main 和当前开发分支）。
提交信息规范 (Conventional Commits)： 格式：<type>(<scope>): <subject>
- feat: 新功能
- fix: 修复 Bug
- refactor: 重构（既不修复 Bug 也不新增功能）
- perf: 性能优化
- style: 代码格式（空格、分号等，不影响逻辑）
- test: 添加测试
- docs: 文档更新
- chore: 构建工具、依赖管理
- 示例： feat(auth): add JWT token refresh logic 或 fix(api): handle null pointer in user list
Code Review 制度：
- 任何代码合并到 main 前，必须发起 Pull Request (PR)。
- PR 需要至少 1-2 人 批准。
- 合并前 CI 必须是绿色（通过所有测试）。
- PR 大小建议：改动文件不超过 10-15 个，行数不超过 500-800 行，大的功能应拆分为多个 PR。

技术栈统一与脚手架约定

统一技术栈可以减少认知成本,建议以下标准选型：

层	技术选型	备注
前端框架	React 18+ / Vue 3+	按团队情况二选一，核心功能（如状态管理、路由）统一使用推荐库。
后端语言	Node.js (TypeScript) / Go / Java	统一语言和运行时，建议使用 Ts。
数据库	PostgreSQL / MySQL	关系型数据库，统一 ORM（如 Prisma, TypeORM, Sequelize）。
API 协议	RESTful API (首选) / GraphQL	统一接口风格，文档需使用 OpenAPI 3.0 规范。
类型系统	TypeScript (全栈)	强烈建议前后端都使用 Ts，能减少大量因类型引发的 Bug。
包管理器	pnpm / yarn	统一锁定文件 (lockfile)。
代码格式化	ESLint + Prettier	配置文件 `.eslintrc` 和 `.prettierrc` 强制团队统一，CI 阶段 lint 未通过直接拦截。
环境变量	`dotenv`	敏感信息不提交到 Git，提供 `.env.example` 示例文件。

项目结构与目录规范

采用 Monorepo 架构管理全栈项目，推荐使用 pnpm workspace 或 turbo。

my-fullstack-app/
├── apps/                # 可部署的应用
│   ├── web/             # 前端应用 (React/Vue)
│   │   ├── src/
│   │   │   ├── pages/         # 页面
│   │   │   ├── components/    # 通用组件
│   │   │   ├── hooks/         # 自定义 Hooks
│   │   │   ├── services/      # API 调用封装
│   │   │   └── utils/         # 工具函数
│   │   ├── public/
│   │   └── package.json
│   └── server/          # 后端应用 (Node/Express/Nest)
│       ├── src/
│       │   ├── modules/       # 按业务模块划分 (如 user, order)
│       │   │   ├── user.controller.ts
│       │   │   ├── user.service.ts
│       │   │   ├── user.model.ts/entity.ts  # 实体/模型
│       │   │   └── user.validation.ts  # 参数校验
│       │   ├── middleware/    # 中间件 (JWT 校验, 日志, 错误处理)
│       │   ├── config/        # 配置
│       │   └── common/        # 公共工具、常量、异常
│       └── package.json
├── packages/            # 共享库
│   ├── shared-types/    # 前后端共享的 TypeScript 类型
│   └── ui-kit/          # 内部 UI 组件库
├── docker/              # Docker 配置
├── .github/             # CI/CD 配置
│   └── workflows/       # GitHub Actions
├── .env.example
├── turbo.json           # 或 lerna.json
└── package.json         # 根 package.json

前后端协作规范

接口定义先行 (API First)：
- 在开发前端功能前,必须先定义 API 接口文档。
- 后端同事提供 Mock 数据或接口定义文件（如 shared-types 包中的类型）。
- 工具： Swagger (OpenAPI), Stoplight, Apifox, YApi。
数据流规范：
- 请求： 使用 Axios 或 Fetch 封装统一的请求拦截器（处理 Token 刷新、请求头设置）。
- 响应： 后端统一返回格式。
```
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "timestamp": 1700000000
}
```
- 错误处理： 约定好 HTTP 状态码含义 (200 成功, 400 参数错误, 401 未认证, 403 无权限, 500 服务器错误)，严格区分业务错误和系统错误。
状态管理：
- 前端负责展示和数据 UI 状态。
- 后端是唯一的数据真实来源 (Source of Truth)。
- 前端应尽可能从后端获取完整的数据结构,避免在前端做复杂的聚合计算（除非性能要求极高）。

编码与质量规范

命名规范：
- 文件： kebab-case (user-profile.tsx, auth-controller.ts)。
- 变量/函数： camelCase (JavaScript/TypeScript)。
- 类/组件/类型： PascalCase。
- 数据库表/字段： snake_case (如 user_id, created_at) — 后端 ORM 中保持使用，前端不直接对接。
- API 路径： 全小写 + 连字符 (GET /api/v1/user-profiles)。
异常与日志：
- 前端： 统一的错误边界 (Error Boundary)，所有 API 请求必须有 .catch() 或 try-catch，控制台不要出现红色报错。
- 后端： 使用 winston / pino 结构化日志，不要使用 console.log，关键业务操作（创建订单、登录失败）必须打印日志。
安全规范：
- 敏感信息绝不硬编码在代码中。
- SQL 注入： 必须使用 ORM 或参数化查询。
- XSS/CSRF： 前端需对用户输入做转义，后端设置正确的 CORS 和 Content-Security-Policy 头。
- 鉴权： 统一使用 JWT (access token + refresh token)，token 存储在 httpOnly Cookie 中（推荐）或 Authorization Header。

开发流程与协作工具

需求与任务管理：
- 工具：Jira, Notion, Linear, Trello。
- 每个功能点对应一个 Ticket，提及 PR 编号。
- 分支命名规范： feat/TA-123-user-registration (包含 Ticket 号)。
CI/CD 流程：
- CI (代码推送时)： Lint -> TypeScript 类型检查 -> 单元测试 -> 构建 -> (可选) 集成测试。
- CD (合并到 main 后): 自动构建 Docker 镜像 -> 推送到容器仓库 -> 触发部署到 Staging/Prod 环境。
环境管理（四套环境）：
- Local (本地开发)： 开发人员本地启动，对接 Mock 或本地 Docker 数据库。
- Dev (开发环境)： 后端最新代码部署，供前端联调。
- Staging (预发布/测试环境)： 与生产环境配置基本一致，供 QA 测试和产品验收。
- Production (生产环境)： 线上环境，严格遵守灰度发布。