AI编码规范要求

lishihuan大约 3 分钟

AI编码规范要求

目标

所有代码应以企业级项目长期维护为目标，优先考虑可读性、可维护性和一致性，而不是单纯追求功能实现或理论上的扩展能力。

一、代码设计原则

1. 保持简单

遵循 KISS（Keep It Simple, Stupid）原则。

  • 优先采用简单直接的实现方案
  • 不为了未来可能的需求进行过度设计
  • 不为了使用设计模式而使用设计模式
  • 当前需求只有一种实现方式时，直接实现即可

避免：

  • 过度抽象
  • 过度封装
  • 过度拆分

2. 遵循现有项目风格

生成代码前应优先分析项目现有实现方式。

保持一致：

  • 包结构
  • 命名规范
  • 返回格式
  • 异常处理方式
  • 日志规范
  • DTO/VO使用习惯
  • Mapper编写风格

禁止无故引入新的架构风格。

3. 优先复用已有代码

开发前应优先搜索：

  • 是否已有类似功能
  • 是否已有工具类
  • 是否已有公共组件
  • 是否已有枚举定义
  • 是否已有DTO、VO对象

避免重复造轮子。

二、编码规范

4. 禁止硬编码

业务相关内容不得直接写死在代码中。

包括但不限于：

  • 状态值
  • 类型值
  • URL路径
  • 配置参数
  • 文件路径
  • 业务编码

应使用：

  • 常量
  • 枚举
  • 配置文件

进行统一管理。

5. 禁止魔法字符串

禁止出现无业务含义说明的字符串。

例如：

"SUCCESS"
"FAILED"
"ADMIN"
"USER"

应定义为：

StatusEnum.SUCCESS
RoleEnum.ADMIN

或：

public static final String STATUS_SUCCESS

6. 禁止魔法数字

禁止直接使用无说明意义的数字。

例如：

if(age > 18)

Thread.sleep(5000)

应定义为：

private static final int ADULT_AGE = 18;

private static final int RETRY_INTERVAL_MS = 5000;

7. 优先使用枚举

涉及以下场景时优先使用枚举：

  • 状态
  • 类型
  • 分类
  • 操作结果
  • 业务标识

避免大量字符串判断。

三、项目结构规范

8. 控制文件拆分粒度

保持合理文件数量。

原则：

  • 一个业务功能尽量集中实现
  • 文件过小且无复用价值时不要单独创建
  • 不要为了拆分而拆分

避免出现：

UserValidator
UserNameValidator
UserPhoneValidator
UserEmailValidator

这类过度细化结构。

9. 控制架构复杂度

对于普通业务系统：

推荐：

Controller
Service
Mapper
Entity
DTO
VO

即可满足需求。

非必要情况下不要新增：

Factory
Assembler
Converter
Manager
Facade
Adapter
Context
Strategy
Handler

等额外层级。

10. 不引入无意义对象转换

简单业务场景：

DTO
↓
Entity
↓
VO

即可。

避免：

DTO
↓
BO
↓
DO
↓
Entity
↓
VO

等多层转换。

四、代码质量要求

11. 保持代码可读性

优先考虑：

  • 清晰命名
  • 合理注释
  • 简洁逻辑

避免：

  • 炫技代码
  • 过长链式调用
  • 复杂嵌套判断

12. 异常处理规范

不得直接吞掉异常。

异常应：

  • 记录日志
  • 返回明确错误信息
  • 保留问题定位能力

避免：

catch(Exception e){}

13. 日志规范

日志应记录：

  • 关键业务动作
  • 异常信息
  • 重要参数

避免：

  • 无意义日志
  • 大量重复日志
  • 输出敏感信息

五、输出要求

生成代码时应遵循以下顺序：

  1. 分析需求
  2. 分析现有项目结构
  3. 给出实现方案
  4. 输出代码
  5. 说明设计原因

如果发现需求存在更合理实现方案，应主动提出建议。

六、适用范围

适用于：

  • Spring Boot
  • Spring Cloud
  • MyBatis
  • Vue2
  • Vue3
  • 企业管理系统
  • 数据管理平台
  • 中后台业务系统

默认目标：

优先可维护性 > 开发效率 > 扩展性 > 理论最佳实践。