/>

一、开发流程

(高效·闭环)

1. 测试先行（TDD

   思维）：功能开发前或开发中，必须同步编写单元测试或集成测试，并完成自测。

   严禁仅实现“快乐路径”而不覆盖异常场景。

2. 启动极速化：开发环境配置必须遵循“一键运行”原则（如

   Java

   命令）。

   禁止依赖复杂的本地容器或需要多步手动干预才能启动的环境。

3. 原子化提交：代码提交应遵循“原子性”原则，即每次提交只解决一个问题、实现一个完整的小功能或修复一个

   Bug。

   禁止一次性提交数百行包含多个不相关功能的代码，确保提交历史清晰可回溯，便于

   Code

   或版本回滚。

4. 强迫症式整洁：AI

   生成代码或手动编码后，必须执行格式化、去除死代码（注释掉的代码块）、消除编译警告（Warning）。

   保持代码风格如一人所写。

5. 复用优先（DRY原则）：开发前先检索现有代码库。

   通用工具类、UI

   组件、Hooks

   等优先复用或重构现有代码，杜绝重复造轮子导致的维护地狱。

二、环境配置

(严谨·自适应)

1. 严格环境隔离：开发

   (Dev)、测试

   密钥）必须物理隔离。

   严禁在开发时连接生产数据库，或在生产环境开启调试模式。

2. 环境自适应（智能切换）：代码应能根据运行环境变量自动加载对应配置（如application-dev.yml或.env.local）。

   严禁在代码中手动修改常量值来切换环境，杜绝误提交导致的生产事故。

3. 配置外部化（12-Factor

   法则）：所有可变配置（如第三方密钥、文件存储路径、线程池大小）必须外置于配置文件、环境变量或配置中心。

   禁止在代码中硬编码任何业务常量以外的值。

4. 依赖可追溯（拉之即跑）：新增任何第三方依赖（Jar包、NPM包）或修改构建脚本，必须在提交信息或注释中说明用途。

   确保团队成员git

   pull后，执行标准命令即可安装依赖并成功运行，无需额外询问。

三、代码质量

(健壮·安全)

1. 清晰的意图注释：接口定义、复杂算法、设计原因（Why）、特殊业务逻辑必须加注释。

   代码即文档，但注释解释“为什么这么做”比“做了什么”更重要。

2. AI

   代码审查机制（红线）：绝对禁止直接复制粘贴不理解原理的

   生成的代码必须经过人工审查：

   • 审查点：是否存在逻辑漏洞？有无资源未关闭？并发场景是否安全？是否符合本规范？
   • 原则：宁可不复用

     代码，也不引入不可控的技术债务。

3. 安全编码底线：
   • 数据操作：涉及事务的方法需确保原子性，关注索引使用情况，使用预编译或

     ORM

     日志。

   • 输入校验：坚信“前端传递的数据皆不可信”。

     所有接口入参（包括内部

     Feign

     调用）必须校验非空、格式、长度、范围。

   • 异常处理：禁止仅e.printStackTrace()或打印日志后不处理。

     异常必须被妥善捕获、事务回滚（如需），并向调用方返回结构统一、语义明确的错误信息。

4. 基础性能意识：避免在循环中调用数据库或远程接口（N+1问题），避免重复计算，合理使用缓存。

   性能敏感代码需进行简单的压力自测。

四、调试与协作

(顺畅·透明)

1. 调试友好（万能开关）：开发环境应提供“调试模式”，允许临时跳过繁琐认证（如短信验证码、图形验证码、第三方

   OAuth

   第三方接口返回。

   但必须确保开关默认关闭，且在测试/生产环境强制开启真实校验逻辑。

2. 前端鲁棒性（体验兜底）：前端不能假设接口永远返回理想数据。

   必须处理：

   • 空状态：列表没数据时的占位提示。

   • 加载中：发起请求时的骨架屏或

     Loading

     动画。

   • 错误态：接口报错或网络超时时的友好提示与重试机制。

3. 接口契约即文档：修改或新增接口，必须同步更新

   Swagger

   文档。

   请求/响应示例必须清晰，字段变更需标注废弃或新增原因，确保前后端联调零障碍。

4. 日志分级（可观测性）：
   • INFO：记录关键业务流程节点（如“用户下单成功，订单号：xxx”）、启动参数。

   • ERROR：必须包含完整的堆栈信息及上下文参数（如userId、orderId），确保仅凭日志即可定位问题，避免因日志不全而被迫复现。

五、提交前自检清单

(可靠·守门员)

提交代码至远程仓库前，请默念并执行以下检查：

1. 全量构建与自测：本地完整运行构建命令（如mvn

   clean

   build），并启动应用进行冒烟测试，确认新功能正常且未影响主流程（如登录、注册）。

2. 代码冲突解决：提交前先从目标分支（如dev）拉取最新代码合并，解决所有冲突，确保本地分支可被

   fast-forward

   或干净合并。

3. 规范速览：快速对照本规范，检查是否有明显遗漏（如配置没外置？没写注释？没加日志？）。