开发规范

元数据

属性	值
领域	技术
责任人	徐聪 (costcodev)
版本	v1.0
创建日期	2026-06-22
标签	开发规范, 代码风格, Git, 项目管理

概述

定义团队统一的代码编写、项目管理、协作流程规范。目的是确保代码可维护、可交接，降低协作摩擦。

正文

一、代码规范

Python
- 遵循 PEP 8 代码风格
- 使用 black 自动格式化，行宽 100
- 类型注解必须（mypy --strict 通过）
- 文档字符串用 Google 风格
TypeScript/JavaScript
- 使用 prettier 格式化
- ESLint 严格模式
- 禁止 any 类型（除非显式标注 // eslint-disable-next-line）
- 所有公共 API 必须有 JSDoc
通用规则
- 函数单一职责，不超过 50 行
- 命名：camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE（常量）
- 禁止 print / console.log 残留（用日志库）
- 禁止注释掉的代码（相信 Git）

二、Git 规范

分支策略

main ─── 生产环境
develop ─── 开发主线
feature/<task-id>-<desc> ─── 功能分支
fix/<task-id>-<desc> ─── 修复分支

Commit 格式
```
<type>(<scope>): <subject>

<body>

<footer>
```
- type: feat / fix / docs / style / refactor / test / chore
- scope: 模块名（如 api, ui, db）
- subject: 不超过 72 字符，中文或英文
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)

变更记录

日期	版本	变更说明	变更人
2026-06-22	v1.0	初始创建	陆怀瑾

2.8 KiB Raw Blame History Unescape Escape

开发规范

元数据

概述

正文

一、代码规范

二、Git 规范

三、项目结构规范

四、文档规范

五、测试规范

相关条目

变更记录

2.8 KiB

Raw Blame History