陆怀瑾 (COO)
104 lines
2.8 KiB
Markdown
104 lines
2.8 KiB
Markdown
# 开发规范
|
||
|
||
## 元数据
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| **领域** | 技术 |
|
||
| **责任人** | 徐聪 (costcodev) |
|
||
| **版本** | v1.0 |
|
||
| **创建日期** | 2026-06-22 |
|
||
| **标签** | 开发规范, 代码风格, Git, 项目管理 |
|
||
|
||
## 概述
|
||
|
||
定义团队统一的代码编写、项目管理、协作流程规范。目的是确保代码可维护、可交接，降低协作摩擦。
|
||
|
||
## 正文
|
||
|
||
### 一、代码规范
|
||
|
||
1. **Python**
|
||
- 遵循 PEP 8 代码风格
|
||
- 使用 `black` 自动格式化，行宽 100
|
||
- 类型注解必须（`mypy --strict` 通过）
|
||
- 文档字符串用 Google 风格
|
||
|
||
2. **TypeScript/JavaScript**
|
||
- 使用 `prettier` 格式化
|
||
- ESLint 严格模式
|
||
- 禁止 `any` 类型（除非显式标注 `// eslint-disable-next-line`）
|
||
- 所有公共 API 必须有 JSDoc
|
||
|
||
3. **通用规则**
|
||
- 函数单一职责，不超过 50 行
|
||
- 命名：camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE（常量）
|
||
- 禁止 `print` / `console.log` 残留（用日志库）
|
||
- 禁止注释掉的代码（相信 Git）
|
||
|
||
### 二、Git 规范
|
||
|
||
1. **分支策略**
|
||
```
|
||
main ─── 生产环境
|
||
develop ─── 开发主线
|
||
feature/<task-id>-<desc> ─── 功能分支
|
||
fix/<task-id>-<desc> ─── 修复分支
|
||
```
|
||
|
||
2. **Commit 格式**
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
- type: feat / fix / docs / style / refactor / test / chore
|
||
- scope: 模块名（如 api, ui, db）
|
||
- subject: 不超过 72 字符，中文或英文
|
||
|
||
3. **PR 流程**
|
||
- 所有代码变更必须通过 PR
|
||
- 至少 1 人 Review 并 Approve
|
||
- CI 全部通过后才能合并
|
||
- 合并前 rebase develop 消除冲突
|
||
|
||
### 三、项目结构规范
|
||
|
||
```
|
||
project/
|
||
├── src/ # 源代码
|
||
├── tests/ # 测试代码
|
||
├── docs/ # 项目文档
|
||
├── scripts/ # 运维脚本
|
||
├── config/ # 配置文件
|
||
├── README.md # 项目说明
|
||
├── CHANGELOG.md # 变更日志
|
||
└── .env.example # 环境变量模板
|
||
```
|
||
|
||
### 四、文档规范
|
||
|
||
- **README.md**：项目概述、快速启动、技术栈、目录说明
|
||
- **API 文档**：后端接口必须有 OpenAPI/Swagger 文档
|
||
- **开发文档**：架构设计、数据流图、部署说明
|
||
- **代码即文档**：优先清晰的命名和结构，减少注释
|
||
|
||
### 五、测试规范
|
||
|
||
- 单元测试覆盖率 ≥ 70%
|
||
- 关键业务逻辑覆盖率 ≥ 90%
|
||
- 每个 PR 附带新增/修改的测试
|
||
- 使用 `pytest` (Python) / `vitest` (TS)
|
||
|
||
## 相关条目
|
||
|
||
- [代码审查清单.md](代码审查清单.md)
|
||
- [PRD模板.md](../产品/PRD模板.md)
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 版本 | 变更说明 | 变更人 |
|
||
|------|------|----------|--------|
|
||
| 2026-06-22 | v1.0 | 初始创建 | 陆怀瑾 | |