1. 文档目的

本文总结一套适用于中小型业务系统与工具型项目的代码开发规范。内容结合常见项目演进中容易出现的实际情况提炼而来，但刻意抽象为通用原则，不依赖任何特定业务背景、技术品牌或目录结构。

目标不是追求“形式上的规范”，而是降低以下成本：

• 新成员理解成本
• 需求变更带来的修改成本
• 排查问题时的定位成本
• 交接、复盘、扩展时的沟通成本

---

2. 总体原则

2.1 单一职责优先

一个模块只解决一类问题。

常见划分方式：

• 接入层：处理外部输入输出、接口调用、协议适配
• 业务层：处理核心业务规则和流程编排
• 基础设施层：日志、配置、存储、工具函数、第三方封装
• 启动层：脚本入口、命令行、服务启动逻辑

如果一个文件同时承担“启动、业务、配置、异常处理、日志拼装”多项职责，通常说明需要拆分。

2.2 先保证边界，再追求复用

复用建立在清晰边界之上。没有边界的“通用封装”往往会快速失控。

推荐顺序：

1. 先把模块职责划清
2. 再抽公共接口
3. 最后再沉淀复用能力

2.3 让目录表达设计，而不是堆放文件

目录结构应该让人一眼看出：

• 哪些是核心代码
• 哪些是入口脚本
• 哪些是测试
• 哪些是设计文档
• 哪些是临时示例或验证代码

如果“示例、测试、工具、正式代码”长期混放，后续维护很容易失焦。

---

3. 代码组织规范

3.1 核心库与启动脚本分离

推荐把可复用能力放在独立包或模块中，把“运行方式”放在轻量入口里。

良好实践：

• 核心逻辑可以被 import 调用
• 启动脚本只负责参数读取、依赖组装、启动流程
• 不在入口脚本中堆积大量业务实现

这样做的价值：

• 更容易测试
• 更容易复用
• 更容易替换运行方式

3.2 避免超大文件

一个文件过大通常意味着职责过多。建议按照“配置、协议、服务、异常、工具、模型”拆分。

经验建议：

• 文件超过数百行时，主动检查是否可以按职责切分
• 类过长时，优先拆出协作对象，而不是继续追加方法

3.3 工具函数必须受控

utils 往往最容易变成“杂物间”。

规范要求：

• 工具函数只能放通用、稳定、无业务语义的能力
• 一旦函数带明显业务语义，就应进入对应领域模块
• utils 目录要按主题继续拆分，不要无限累积

---

4. 配置管理规范

4.1 配置必须显式建模

配置不要散落在脚本常量、环境变量读取、JSON/YAML 字典访问中。

推荐做法：

• 用明确的数据结构承载配置
• 在启动阶段统一加载和校验
• 对外暴露默认值、必填项、取值范围

4.2 环境变量只作为输入，不作为业务逻辑来源

环境变量适合承载部署差异，不适合在业务代码中被随意读取。

推荐做法：

• 统一从配置层读取环境变量
• 业务层只接收已经校验完成的配置对象
• 敏感信息不写入日志、不硬编码、不提交到仓库

4.3 配置校验前置

系统应在启动早期失败，而不是在运行中随机失败。

至少校验：

• 必填字段
• 枚举值范围
• 数值上下限
• 外部依赖前置条件

---

5. 异常与日志规范

5.1 异常要分层，不要一把抓

建议建立清晰的异常层次：

• 参数异常
• 配置异常
• 外部依赖异常
• 业务规则异常
• 系统运行异常

不建议到处直接抛出模糊的通用异常文本。

5.2 日志服务于排查，而不是制造噪音

日志应该回答三个问题：

• 发生了什么
• 为什么发生
• 影响了什么

推荐要求：

• 关键流程打信息日志
• 高频成功路径避免刷屏
• 异常日志带上下文信息
• 敏感字段统一脱敏

5.3 失败信息要可定位

错误日志中至少应保留：

• 当前操作
• 关键参数标识
• 外部调用结果或状态
• 重试次数或恢复动作

---

6. 测试规范

6.1 测试目录必须统一口径

测试结构混乱会直接拉高维护成本。

建议固定一种组织方式，并长期坚持：

• 单元测试：围绕模块与函数
• 集成测试：围绕模块协作与外部依赖
• 示例代码：独立于正式测试目录

不要让“示例、脚本、手工验证、自动化测试”边界模糊。

6.2 先测核心规则，再测外部联动

优先级建议：

1. 配置解析与校验
2. 核心业务规则
3. 异常分支与边界条件
4. 与外部系统的集成流程

6.3 测试要能表达意图

测试名称要让人看懂场景、输入和预期结果。

好的测试通常能回答：

• 前置条件是什么
• 执行动作是什么
• 期望结果是什么

---

7. 文档规范

7.1 README 只做入口，不做百科全书

README 推荐包含：

• 项目简介
• 快速启动
• 主要能力
• 文档导航
• 最低环境要求

细节说明应下沉到专题文档。

7.2 文档链接必须可验证

常见问题不是“没写文档”，而是“文档索引失真”。

建议定期检查：

• 链接是否存在
• 目录名称是否一致
• 文档是否仍与代码实现匹配

7.3 文档结构与代码结构对应

推荐至少区分：

• 用户文档
• 技术文档
• 开发文档
• 外部协议或依赖说明

这样更利于读者按角色获取信息。

---

8. 命名与风格规范

8.1 命名优先表达语义

命名标准：

• 变量名表达含义，不追求缩写炫技
• 类名体现对象职责
• 函数名体现动作和结果
• 文件名与模块职责一致

8.2 注释解释“为什么”，少解释“是什么”

以下情况值得写注释：

• 设计取舍
• 兼容性约束
• 时序要求
• 容易误用的边界条件

不建议用注释重复代码字面意思。

8.3 风格统一优先于个人偏好

团队规范应覆盖：

• 格式化工具
• import 顺序
• 类型标注要求
• 日志与异常写法
• 测试命名方式

一旦选定，就自动化执行，不靠人工争论。

---

9. 常见工程化问题与改进建议

以下问题在很多项目中都会出现：

9.1 入口脚本过重

表现：

• 启动文件同时承担大量业务逻辑
• 难以复用和测试

建议：

• 把流程编排和底层能力拆开
• 入口只保留组装与启动

9.2 文档与实现逐渐脱节

表现：

• 目录说明和真实结构不一致
• 文档引用失效

建议：

• 文档纳入评审范围
• 每次结构调整同步更新导航文档

9.3 测试口径不统一

表现：

• 自动化测试、样例代码、手工验证脚本混杂

建议：

• 建立统一分类
• 明确哪些进入 CI，哪些只做示例

9.4 配置分散

表现：

• 默认值、环境变量、配置文件、命令行参数散布在多个位置

建议：

• 收敛到统一配置入口
• 统一校验、统一说明、统一默认值策略

---

10. 建议落地顺序

如果一个项目已经在运行，不建议一次性“大重构”，更合理的顺序是：

1. 统一目录和命名规则
2. 收敛配置入口和校验逻辑
3. 拆分过重模块
4. 清理测试分类
5. 修正文档索引和开发说明
6. 接入格式化、静态检查、测试自动化

这个顺序的核心思路是：先让工程边界稳定，再提高质量门槛。

---

11. 结论

开发规范的价值不在于“写得漂亮”，而在于让系统可以持续演进。

一套有效的规范，应该同时满足三点：

• 新人能快速理解
• 老代码能逐步收敛
• 团队能通过工具自动执行

真正好的规范，不依赖某个负责人反复提醒，而是能自然体现在目录、代码、测试、文档和提交流程中。