1. 文档目的
本文总结一套适用于中小型业务系统与工具型项目的代码开发规范。内容结合常见项目演进中容易出现的实际情况提炼而来，但刻意抽象为通用原则，不依赖任何特定业务背景、技术品牌或目录结构。
目标不是追求"形式上的规范"，而是降低以下成本：
- 新成员理解成本
- 需求变更带来的修改成本
- 排查问题时的定位成本
- 交接、复盘、扩展时的沟通成本
2. 总体原则
2.1 单一职责优先
一个模块只解决一类问题。
常见划分方式：
- 接入层：处理外部输入输出、接口调用、协议适配
- 业务层：处理核心业务规则和流程编排
- 基础设施层：日志、配置、存储、工具函数、第三方封装
- 启动层：脚本入口、命令行、服务启动逻辑
如果一个文件同时承担"启动、业务、配置、异常处理、日志拼装"多项职责，通常说明需要拆分。
2.2 先保证边界，再追求复用
复用建立在清晰边界之上。没有边界的"通用封装"往往会快速失控。
推荐顺序：
- 先把模块职责划清
- 再抽公共接口
- 最后再沉淀复用能力
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 先测核心规则，再测外部联动
优先级建议：
- 配置解析与校验
- 核心业务规则
- 异常分支与边界条件
- 与外部系统的集成流程
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. 建议落地顺序
如果一个项目已经在运行，不建议一次性"大重构"，更合理的顺序是：
- 统一目录和命名规则
- 收敛配置入口和校验逻辑
- 拆分过重模块
- 清理测试分类
- 修正文档索引和开发说明
- 接入格式化、静态检查、测试自动化
这个顺序的核心思路是：先让工程边界稳定，再提高质量门槛。
11. 结论
开发规范的价值不在于"写得漂亮"，而在于让系统可以持续演进。
一套有效的规范，应该同时满足三点：
- 新人能快速理解
- 老代码能逐步收敛
- 团队能通过工具自动执行
真正好的规范，不依赖某个负责人反复提醒，而是能自然体现在目录、代码、测试、文档和提交流程中。