后端项目 AI 开发规范（AI Coding Rules）

本文档用于约束 AI 编程助手在本项目中的代码生成、代码修改、重构、SQL 编写、数据库设计、接口设计、Git 操作建议以及代码审查行为。

AI 在参与本项目开发时，必须优先遵守本规范。

核心目标：

码出高效，码出质量，保证代码统一、可读、可维护、可扩展、可测试、可追踪。

0. AI 总体行为准则

0.1 基本原则

AI 在生成或修改项目代码时，必须遵循以下原则：

正确性
   ↓
安全性
   ↓
数据一致性
   ↓
可维护性
   ↓
可读性
   ↓
性能
   ↓
代码简洁程度

不得为了“代码更短”牺牲：

可读性
稳定性
数据一致性
可维护性
安全性

0.2 AI 不允许擅自扩大修改范围

如果任务是：

修复订单分页查询 Bug

AI 不应顺手：

重构整个订单模块
升级 Spring Boot
修改数据库字段
调整公共工具类
修改其他无关代码

除非这些修改是解决当前问题所必需。

遵循：

最小必要修改原则。

0.3 AI 修改现有项目时优先遵循已有风格

如果本规范与项目现有代码没有冲突，必须遵循本规范。

如果项目已经形成明确统一的现有约定，例如：

现有 DTO 命名规则
现有异常体系
现有 Result 返回结构
现有 Mapper 规范
现有日志规范
现有包结构

AI 不应自行创造第二套体系。

优先：

理解现有项目
→ 复用现有设计
→ 最小范围修改
→ 保持统一

而不是：

重新设计整个项目

0.4 AI 不得凭空创建基础设施

如果项目已经存在：

Result
BaseException
RedisUtils
UserService
OrderMapper
SecurityUtils

必须优先复用。

禁止因为不知道现有实现就自行生成：

Result2
ResponseResult
NewRedisUtils
CommonException2

造成重复封装。

1. 基础环境规范

1.1 文件路径规范

源码及开发环境相关目录中：

Java
Vue
IDE
JDK
MySQL
Redis
RabbitMQ
Nacos
Maven
Git

所在路径禁止包含：

中文
空格
无必要特殊字符

推荐：

D:/develop/jdk8
D:/develop/mysql
D:/workspace/order-service

不推荐：

D:/开发工具/JDK 8/
D:/我的项目/order service/

2. Java 开发规范

Java 开发默认遵循：

《Java 开发手册（黄山版）》

如果本规范进行了更具体约束，以本项目规范为准。

当前项目默认 Java 版本：

JDK 8

因此 AI 不得生成当前 JDK 无法支持的 Java 语法。

例如未经项目升级，不得默认使用：

record
sealed class
var
switch expression
text block

等高版本特性。

3. 配置文件规范

以下本地环境配置原则上不得提交至 Git：

application-local.yml
application-local.yaml
application-local.properties

以及：

开发人员本机数据库密码
Redis 密码
本地 Nacos 地址
个人 AccessKey
SecretKey
Token
其他敏感信息

AI 如果发现密码、Token、密钥被硬编码进代码或配置文件，应主动指出。

敏感信息必须通过：

环境变量
配置中心
密钥管理系统
部署平台配置

等方式提供。

4. 开发工具统一规范

团队默认开发工具：

IDE：
IntelliJ IDEA

数据库：
Navicat

接口文档 / 接口测试：
Apifox

JDK：
JDK 8

版本管理：
Git

代码仓库：
GitHub

IntelliJ IDEA 必须安装 Alibaba Java Coding Guidelines 插件。

项目正式上线后，接口文档需要做好归档。

5. Git 提交规范

AI 在帮助生成 Commit Message 或分支名称时，必须使用以下规范。

5.1 新功能

格式：

feat/module_name

Commit：

feat/module_name: 具体开发内容

示例：

feat/multi_merchant: 支持多商户下单

feat/order: 增加订单导出功能

5.2 普通 Bug 修复

格式：

bugfix/fix_name

示例：

bugfix/user

Commit：

bugfix/user: 修复手机号为空导致登录失败的问题

5.3 线上紧急修复

格式：

hotfix/fix_name

例如：

hotfix/create_order

Commit：

hotfix/create_order: 修复重复提交导致订单重复创建的问题

hotfix 主要用于：

严重线上 Bug
生产事故
影响核心业务的问题

5.4 性能优化

必须使用：

perf

禁止写成：

pref

格式：

perf/name

示例：

perf/user_login

Commit：

perf/user_login: 优化用户登录查询性能

5.5 不影响业务逻辑的代码调整

使用：

style

例如：

style/log_print: 调整日志格式

适用于：

删除无用注释
格式整理
删除无用 import
无业务影响的代码格式调整

不得将业务重构错误标记为 style。

5.6 重构

使用：

refactor

例如：

refactor/user: 重构用户注册流程

重构原则：

改变代码结构，但原则上不改变业务行为。

5.7 测试

使用：

test

例如：

test/user: 补充用户登录单元测试

适用于：

单元测试
集成测试
测试数据
测试代码

5.8 文档

使用：

docs

例如：

docs/order: 补充订单状态接口说明

适用于：

README
接口文档
技术文档
代码注释

5.9 工程维护

使用：

chore

例如：

chore/dependency: 升级公共依赖版本

适用于：

Maven
依赖
构建脚本
脚手架
工程配置
CI 配置

5.10 Commit 信息要求

禁止使用：

fix
update
修改
优化
测试
代码调整
解决问题
123

Commit 必须说明：

修改类型
+
修改模块
+
具体做了什么

推荐：

bugfix/order: 修复取消订单后库存未释放的问题

而不是：

fix order

6. Git 分支规范

核心分支：

分支	是否保护	说明
test	是	测试环境
pre	是	预发布环境
prod	是	正式生产环境
master	是	生产代码存档，与 prod 保持同步
feat/* 等	否	开发分支

6.1 已上线项目

如果系统已经上线：

新功能、普通修复原则上从当前线上稳定代码创建分支：

prod

或者团队明确指定的：

master

例如：

git checkout prod
git pull
git checkout -b feat/order_export

不得默认从 test 拉取。

原因：

test 中可能存在尚未上线代码

6.2 未上线项目

未正式上线项目，从：

test

拉取最新代码。

例如：

git checkout test
git pull
git checkout -b feat/user_login

6.3 线上 Hotfix

生产环境 Bug 必须基于当前生产代码处理。

推荐：

prod
 ↓
hotfix/*
 ↓
Review
 ↓
生产发布流程

禁止：

test
 ↓
hotfix
 ↓
prod

避免把测试环境中尚未上线的功能带入生产。

6.4 公共分支禁止直接开发

禁止直接在：

test
pre
prod
master

编写业务功能。

必须：

稳定分支
   ↓
开发分支
   ↓
开发
   ↓
Push
   ↓
MR / PR

7. Merge Request / Pull Request 规范

开发完成后：

开发分支
 ↓
push 远程仓库
 ↓
创建 MR / PR
 ↓
目标 test

例如：

feat/multi_merchant
       ↓
      test

然后：

将 MR / PR 链接发送团队群
@技术负责人
等待 Code Review

未经 Review：

不得合并。

7.1 Code Review 重点

AI 在执行 CR 时，应重点检查：

业务逻辑
空指针
异常处理
事务
幂等
并发
SQL
索引
数据库一致性
安全问题
SQL 注入
权限
参数校验
日志
性能
重复代码
代码可读性
模块依赖
接口兼容性

不要只检查代码格式。

7.2 CI/CD

代码 Merge 后，通过 CI/CD：

Checkout
 ↓
Build
 ↓
Test
 ↓
Package
 ↓
Image
 ↓
Deploy

原则上不应依赖人工登录服务器执行：

git pull
mvn package
java -jar

完成正常环境发布。

8. 数据库字符集和存储引擎

MySQL 默认：

字符集：
utf8mb4

存储引擎：
InnoDB

9. 数据库命名规范

数据库名：

与项目名保持一致

数据库、表、字段：

小写字母
数字
下划线

禁止：

数字开头
中文
驼峰表名

例如：

推荐：

b_order_info
b_user_address
b_payment_record

不推荐：

OrderInfo
orders
订单表
1_order

10. 表名规范

业务表推荐：

b_业务名称_表用途

例如：

b_order_info
b_order_item
b_user_address

原则上使用单数业务概念。

例如：

推荐：

order
user
product

而不是：

orders
users
products

10.1 禁止滥用缩写

表名和字段名尽量使用完整、有意义的英文单词。

避免：

usr
ord
prod
cont

如果缩写容易产生歧义，必须使用完整名称。

建议名称长度不超过：

32 个字符

11. 数据库注释规范

数据库：

表必须有注释
字段必须有注释

AI 创建 DDL 时不得省略必要 COMMENT。

例如：

`status` tinyint unsigned NOT NULL DEFAULT 0 COMMENT '订单状态'

12. 主键规范

每张业务表：

必须存在主键

原则上只有一个主键。

统一命名：

id

推荐：

id bigint NOT NULL

具体 ID 生成策略根据项目现有方案：

数据库自增
雪花算法
分布式 ID

不得擅自引入另一种 ID 体系。

13. 索引规范

唯一索引：

uk_字段名

例如：

uk_order_no

普通索引：

idx_字段名

例如：

idx_user_id

组合索引：

idx_user_id_status

13.1 索引数量

单表索引数量原则上：

不要超过 6 个

但该规则不是机械限制。

如果业务确实需要更多索引，需要根据：

查询频率
数据量
写入压力
选择性
执行计划

综合判断。

13.2 索引选择性

优先在：

选择性较高
查询频率较高
过滤能力较强

的字段建立索引。

不应机械地单独在低选择性字段建立索引，例如：

sex
普通二值 status
is_deleted

如果这些字段与其他高选择性字段形成联合索引，应结合真实查询分析。

14. NULL 与默认值

字段应根据业务设置合理默认值。

尽量减少无业务意义的 NULL。

例如：

0
''
默认状态

但 AI 不得为了“禁止 NULL”而破坏字段本身的业务语义。

如果：

NULL = 尚未发生 / 未填写

具有真实业务含义，可以合理使用 NULL。

15. 金额与小数类型

涉及：

金额
费率
价格
余额
手续费

Java 必须使用：

BigDecimal

MySQL 使用：

DECIMAL

禁止用于金额：

float
double
FLOAT
DOUBLE

16. VARCHAR 规范

VARCHAR 长度必须按照业务合理设置。

原则上如果文本长度非常大，例如超过约：

应评估：

TEXT
对象存储 OSS
独立大字段表

不能无脑：

varchar(10000)
varchar(65535)

17. 布尔字段规范

表达：

是否
开启 / 关闭
存在 / 不存在
启用标识

推荐命名：

is_xxx

例如：

is_open
is_deleted
is_default

数据库类型：

tinyint unsigned

约定：

1 = 是
0 = 否

18. 公共字段规范

业务表至少应考虑：

id
created_time
created_by

根据业务需要增加：

updated_time
updated_by

推荐：

id bigint
created_time datetime
created_by bigint
updated_time datetime
updated_by bigint

如果项目已有统一：

BaseEntity
自动填充机制
MyBatis Plus MetaObjectHandler

应复用现有实现。

19. 常用字段命名

推荐：

status
state
remark

其中具体含义必须由：

字段注释
枚举
业务文档

明确。

不得仅依赖：

等魔法数字理解业务。

20. 数据库冗余字段

允许适度冗余，提高查询性能。

但必须满足：

冗余收益明确
数据来源明确
更新机制明确
一致性策略明确

例如订单保存：

商品名称快照
商品价格快照
收货地址快照

可以是合理冗余。

禁止为了“少写 Join”随意复制大量数据。

21. SQL 查询规范

21.1 禁止 SELECT *

禁止：

SELECT *
FROM b_order;

必须明确字段：

SELECT
    id,
    order_no,
    user_id,
    status,
    created_time
FROM b_order;

原因：

降低无效数据传输
减少字段耦合
提高覆盖索引可能性
避免表结构变化影响接口

21.2 SQL 不得机械迷信规则

对于：

!=
<>
IS NULL
OR

AI 不得简单断言：

“一定导致索引失效”

而应该：

结合索引
数据分布
MySQL 优化器
EXPLAIN
真实执行计划

判断。

原则：

尽量写有利于索引和优化器执行的 SQL，但最终以执行计划为依据。

21.3 OR 查询

对于复杂 OR：

WHERE a = ?
   OR b = ?

如果执行计划表现较差，可以考虑：

UNION ALL

但必须保证：

结果语义一致
是否允许重复数据
索引可使用

不得机械替换。

21.4 模糊查询

以下查询：

LIKE '%keyword%'

普通 B-Tree 索引通常无法有效完成前缀定位。

对于：

大数据量
高频搜索
全文搜索

应评估：

Elasticsearch
专业全文检索方案
倒排索引

不得让核心接口长期依赖大表全模糊扫描。

21.5 联合索引

多个 WHERE 条件可以考虑联合索引。

例如：

WHERE user_id = ?
  AND status = ?
  AND created_time >= ?

索引：

idx_user_id_status_created_time

设计时考虑：

最左匹配
字段选择性
排序
范围查询
覆盖索引
真实 SQL

不得只按字段出现顺序机械创建联合索引。

21.6 避免超大 SQL

对于非常复杂的大查询，应评估是否可以：

拆分查询
预聚合
缓存
离线计算
ES
冗余字段
中间表

但拆分 SQL 也会增加：

网络调用
数据库往返
应用计算
数据一致性问题

因此必须根据实际性能决定。

22. EXPLAIN

重要 SQL 必须关注执行计划。

至少检查：

type
possible_keys
key
key_len
rows
filtered
Extra

通常优先追求：

const
eq_ref
ref
range

但 AI 不得简单使用：

system、cost 是最优

这种错误或过度简化的说法。

最终应综合：

扫描行数
索引
回表
排序
临时表
数据量
执行耗时

判断。

23. 隐式类型转换

查询参数类型必须尽量与数据库字段类型一致。

例如数据库：

user_id BIGINT

Java / SQL 参数应使用相匹配的数字类型。

避免：

数字字段传字符串
字符串字段传数字

导致隐式类型转换、索引效果下降或语义异常。

24. Java 命名规范

代码命名禁止：

以下划线开头
以下划线结尾
以 $ 开头
以 $ 结尾

普通业务代码不得随意使用 $。

25. 禁止拼音式命名

禁止：

userXinxi
dingdanService
getYonghu

应使用完整英文：

userInfo
orderService
getUser

已经形成国际通用名称或专有名称除外，例如：

Hangzhou
Taobao
Alipay

26. 类名规范

使用：

UpperCamelCase

例如：

UserManagerServiceImpl
OrderController
PaymentService

27. 方法和变量命名

使用：

lowerCamelCase

例如：

addUserInfo()
createOrder()
userId
orderNo

28. Service / DAO 方法命名

查询单个对象

推荐：

get

例如：

getUser()
getUserById()

查询多个对象

推荐：

list

例如：

listUsers()
listOrders()

如果项目历史规范已经统一：

getUserList()

则保持项目现有风格。

不要一个项目中同时出现三种没有规律的命名。

统计

推荐：

count

例如：

countUsers()
countOrdersByStatus()

新增

使用：

save
insert
create

例如：

saveUser()
insertOrder()
createPayment()

其中：

create

更适合业务动作，

insert

更适合 DAO / Mapper 持久层动作。

删除

使用：

remove
delete

例如：

deleteUserById()
removeOrder()

修改

使用：

update

例如：

updateUser()
updateOrderStatus()

29. 常量规范

常量名称：

全部大写
单词之间使用 _

例如：

private static final int MAX_RETRY_COUNT = 3;

禁止：

private static final int maxRetryCount = 3;

作为常量命名。

30. 常量作用域

常量放置位置必须遵循：

作用范围越小越好。

优先级：

类内
 ↓
包内
 ↓
模块内
 ↓
应用内
 ↓
跨服务

不要因为“以后可能会用”就把常量全部放进：

CommonConstants
GlobalConstants

30.1 跨服务常量

真正跨服务共享时，放入项目约定的公共模块，例如：

lamp-common

的：

constant

目录。

30.2 应用级共享常量

多个子模块使用，可以放入：

lamp-xxx-entity/constant

等项目现有公共位置。

30.3 模块级常量

只被当前模块使用：

当前模块 constant

30.4 类内常量

只被单个类使用：

private static final

直接定义在类内部。

31. 枚举规范

枚举类建议：

Enum

结尾。

例如：

OrderStatusEnum
PaymentTypeEnum

枚举成员：

全大写
下划线分割

例如：

WAIT_PAY
PAY_SUCCESS
PAY_FAILED

禁止在代码中大量出现没有说明的：

if (status == 3)

应该使用：

OrderStatusEnum.PAY_SUCCESS

或者项目现有的枚举值体系。

32. 工具类规范

工具类统一：

Utils

作为后缀。

例如：

JsonUtils
DateUtils
EncryptUtils

但如果成熟类库已有能力：

Hutool
Apache Commons
Spring
JDK

禁止无意义重新封装。

33. 类命名补充

抽象类：

Abstract
Base

例如：

AbstractPaymentHandler
BaseController

异常类：

Exception

结尾。

例如：

OrderCreateException

测试类：

被测试类名 + Test

例如：

OrderServiceTest

34. 设计模式应体现在命名中

如果代码明确使用设计模式，应让名称表达职责。

例如：

PaymentStrategy
AlipayPaymentStrategy
PaymentStrategyFactory
OrderState
PaymentHandler

而不是：

PaymentUtil1
PaymentManager2
CommonHandler

35. 注释规范

对于：

核心类
公共接口
公共方法
复杂业务逻辑
关键字段

必须有必要说明。

JavaDoc 至少描述：

类的职责
方法做什么
重要参数
返回值
异常或限制

例如：

/**
 * 创建订单。
 *
 * @param request 创建订单参数
 * @return 订单 ID
 */
public Long createOrder(CreateOrderRequest request) {
}

35.1 禁止低质量注释

禁止：

// 获取用户
User user = getUser();

这种重复代码含义的无价值注释。

注释应该解释：

为什么这么做
业务限制是什么
容易误解的地方是什么
为什么不能直接修改

35.2 注释必须同步维护

AI 修改代码时：

如果原注释已经错误，必须一起修改。

不能出现：

代码是 A
注释还描述 B

错误注释比没有注释更加危险。

36. DTO / VO / Entity Copy

对象转换时：

优先使用项目已有方案。

如果项目已经统一：

MapStruct
BeanUtils
BeanCopier
手工 mapping

继续使用。

禁止因为方便随意混入多套对象转换技术。

对于性能敏感、大量循环对象转换：

应避免高开销反射式复制。

37. Java 8 特性

可以合理使用：

Lambda
Stream
Optional
Method Reference
CompletableFuture

但禁止为了“显得高级”强行使用。

例如简单循环：

for (...)

如果更清晰，就无需强行改成复杂 Stream。

原则：

可读性优先于炫技。

38. Hutool

项目允许使用 Hutool。

可以合理使用：

JSONUtil
StrUtil
MapUtil
DateUtil
CollUtil

但使用前必须判断：

项目是否已经引入 Hutool
当前版本是否支持
JDK 是否已有更直接方案
Spring 是否已经提供相同能力

禁止为了调用一个简单方法额外增加重量依赖。

39. API 路径规范

外部 API 统一考虑增加：

/api

例如：

https://example.com/api/pay/goPay

RESTful 风格优先推荐：

POST /api/orders
GET  /api/orders/{id}
POST /api/payments

如果项目已经有统一接口风格，以已有项目规则为准。

40. 对外接口字段规范

给：

H5
APP
第三方
前端

提供接口时：

只返回调用方真正需要的数据。

禁止直接暴露数据库 Entity。

例如禁止：

return userEntity;

推荐：

return userVO;

避免泄露：

内部字段
敏感字段
数据库设计
无关字段

41. MyBatis SQL 注入规范

禁止：

${param}

直接拼接用户输入。

例如禁止：

WHERE username = '${username}'

必须优先：

WHERE username = #{username}

${} 只有在确实需要动态 SQL 结构，并且输入经过严格白名单控制的情况下才能使用，例如：

动态排序字段
动态表名

也不能直接信任用户传值。

42. 参数校验

重要接口必须进行参数合法性校验。

例如：

不能为空
长度
范围
格式
枚举合法性
金额
ID
时间区间
分页大小

Controller 层可结合：

@Valid
@Validated

业务规则仍应在业务层校验。

43. 方法长度

Java 方法原则上控制在：

100 行以内

如果一个方法过长，优先：

拆职责
提取方法
划分业务步骤
使用合适的设计模式

但禁止为了满足“100 行”机械拆成：

method1()
method2()
method3()

却没有提高语义和可读性。

44. 方法参数规范

当方法参数超过：

3 个

应优先考虑：

Request
Command
DTO
Query Object

封装。

例如不推荐：

createOrder(
    Long userId,
    Long productId,
    Integer quantity,
    BigDecimal amount,
    String address
);

推荐：

createOrder(CreateOrderRequest request);

45. 幂等性

重要接口必须考虑幂等。

重点包括：

创建订单
支付
退款
支付回调
消息消费
优惠券领取
积分发放
库存扣减
重复表单提交
第三方回调

AI 在生成这些代码时必须主动考虑：

幂等 Key
业务唯一键
数据库唯一索引
状态机
Redis
分布式锁
去重表
消息幂等

选择哪一种由具体业务决定。

46. 支付回调

支付回调必须默认考虑：

重复通知
乱序通知
超时
网络重试
业务处理失败
状态重复更新

例如：

支付平台返回成功
↓
本地业务处理失败

必须考虑：

补偿
重试
对账
消息
人工修复

不能简单认为：

第三方调一次 = 本地一定成功

47. 分布式一致性

跨：

数据库
Redis
MQ
第三方支付
远程服务

修改数据时，必须考虑一致性。

AI 应主动分析：

本地事务
最终一致性
事务消息
Outbox
补偿
重试
状态机
幂等

不得用一个本地 @Transactional 假装解决跨服务事务。

48. 模块依赖

模块之间必须避免：

循环依赖
双向依赖
底层模块依赖上层模块

例如禁止：

order → payment
payment → order

形成直接循环依赖。

应考虑：

事件
接口抽象
公共领域模型
中间协调层
重新划分职责

49. 设计应考虑变化

对于明显具有多实现可能性的业务，设计时应考虑扩展性。

例如登录方式：

账号密码
验证码
微信授权
第三方 OAuth

支付方式：

支付宝
微信支付
银行卡
其他第三方支付渠道

这类业务可以评估：

Strategy
Factory
Template Method
Chain of Responsibility
Adapter

但：

不允许为了“未来可能需要”而过度设计。

只有真实存在多个变化方向或者扩展概率较高时才引入设计模式。

50. NULL 处理

变量使用前必须根据业务判断：

是否可能为空
为空意味着什么
应该返回什么
是否应该抛异常

禁止无意义：

if (obj != null) {
    ...
}

一路吞掉问题。

同时禁止：

try {
} catch (Exception e) {
}

静默忽略异常。

51. 魔法值

不变值或具有明确业务意义的值，应使用：

常量
枚举
配置

禁止：

if (status == 7) {
}

应该尽可能：

if (OrderStatusEnum.CLOSED.getCode().equals(status)) {
}

52. 条件判断

优先保持清晰的分支逻辑。

不应机械规定：

所有场景必须 if-else

或者：

绝对不能连续 if

应根据业务语义选择。

可以优先：

Guard Clause
提前返回

降低深层嵌套。

例如：

if (user == null) {
    throw new UserNotFoundException();
}

if (!user.isEnabled()) {
    throw new UserDisabledException();
}

doBusiness(user);

通常比：

if (user != null) {
    if (user.isEnabled()) {
        ...
    }
}

更清晰。

53. 循环数据库访问

禁止出现明显：

N+1 查询
循环单条 INSERT
循环远程调用

例如不推荐：

for (Long id : ids) {
    userMapper.selectById(id);
}

应该优先：

批量查询

例如：

WHERE id IN (...)

54. 批量写入

大批量插入或修改，应使用：

batch insert
batch update
分批处理

不能无限制一次提交几十万条。

AI 应根据数据量考虑：

批次大小
事务大小
内存
数据库压力
锁
超时

55. DAO / Mapper 层职责

DAO / Mapper 层主要负责：

数据访问
CRUD
查询
持久化

复杂业务逻辑应该放在：

Service / Domain

禁止将大量业务判断塞进 DAO。

56. Service 层职责

Service 层负责：

业务规则
事务
流程编排
状态变化
业务校验

Controller 不应包含大量核心业务逻辑。

推荐：

Controller
   ↓
Service
   ↓
DAO / Mapper

57. 避免重复造轮子

如果成熟库已经存在可靠实现：

优先使用。

例如：

JDK
Spring
Apache Commons
Hutool
Guava
项目公共组件

禁止随意重复实现：

字符串工具
日期格式化
JSON
集合判断
HTTP 基础能力
加密基础算法

尤其安全相关能力不得自行发明算法。

58. 多线程规范

多线程环境必须考虑：

原子性
可见性
有序性
线程安全
资源竞争
死锁
线程池
上下文传递
异常

禁止：

new Thread(...).start();

在业务代码中随意创建线程。

优先使用项目统一线程池。

59. 线程池

线程池必须合理配置：

corePoolSize
maximumPoolSize
queue
keepAliveTime
RejectedExecutionHandler
ThreadFactory

禁止无界队列导致：

OOM
任务无限堆积

60. 日志规范

日志必须使用正确级别：

TRACE
DEBUG
INFO
WARN
ERROR

原则：

正常业务关键节点 → INFO

开发调试信息 → DEBUG

可恢复异常 → WARN

需要人工关注的失败 → ERROR

禁止：

所有东西 INFO
所有异常 ERROR

60.1 禁止打印敏感信息

日志禁止打印：

密码
完整身份证号
银行卡号
支付密钥
AccessToken
RefreshToken
验证码
SecretKey
完整手机号
其他敏感个人信息

需要日志记录时必须脱敏。

60.2 异常日志

不得：

log.error("error");

丢失上下文。

推荐至少带：

业务标识
关键参数
异常对象

例如：

log.error("Create order failed, orderNo={}", orderNo, e);

61. 调用频率意识

AI 在设计任何方法、SQL、Redis、MQ 或第三方请求时，都需要考虑：

一天调用多少次
一分钟多少次
一秒多少次
峰值 QPS
并发量
数据量
增长速度

尤其是高频方法，需要主动评估：

数据库
Redis
MQ
锁竞争
网络
线程池
CPU
内存
第三方 API

压力。

62. 高频接口性能

对于高频接口，需要考虑：

索引
缓存
本地缓存
批处理
异步
削峰
限流
连接池
对象创建
序列化
日志量

不得只关注：

单次代码是否能跑通

63. Redis 使用规范

使用 Redis 前必须先判断：

为什么使用
缓存什么
TTL 多久
如何失效
如何更新
缓存穿透
缓存击穿
缓存雪崩
数据一致性

不得：

所有数据库数据全部缓存

64. 分布式锁

使用 Redis 分布式锁必须考虑：

唯一 owner
过期时间
锁续期
异常释放
finally
原子释放
重入问题
业务执行时间

禁止：

GET
DEL

简单实现不安全的锁释放逻辑。

65. RabbitMQ / MQ

消息消费必须默认考虑：

重复消费
消费失败
重试
死信
乱序
堆积
幂等
ACK
消息丢失

生产端考虑：

发送失败
确认机制
事务一致性

66. Nacos / 配置中心

配置中心适合：

环境配置
可动态调整配置
服务配置

敏感信息是否可以直接存放需要根据公司安全方案决定。

禁止把：

应该是常量的代码逻辑
复杂业务规则
整个 JSON 业务数据库

无脑塞入配置中心。

67. Controller 规范

Controller 主要负责：

接收参数
参数校验
权限入口
调用 Service
返回结果

Controller 不应该承担：

复杂业务流程
大量数据库操作
复杂计算

68. Entity / DTO / VO 职责

建议区分：

Entity
数据库对象

DTO / Request
接口输入或业务传输对象

VO / Response
接口输出对象

不要所有层都使用同一个 Entity。

这样可以避免：

数据库变化影响 API
前端传入不允许修改的数据库字段
敏感字段泄露
业务边界混乱

69. 异常处理

业务异常和系统异常应区分。

例如：

库存不足
订单不存在
优惠券已过期

属于：

业务异常

而：

数据库连接失败
Redis 不可用
网络异常
代码 NPE

属于：

系统异常

禁止所有异常：

catch (Exception e) {
    return false;
}

70. 事务规范

事务范围应尽量小。

禁止：

事务中长时间 HTTP 调用
事务中等待用户操作
事务中做大文件处理
事务中执行长时间计算

AI 添加：

@Transactional

前必须判断：

事务边界
异常回滚
传播行为
自调用问题
跨服务是否有效

71. 接口安全

重要接口需要评估：

认证
授权
参数校验
越权
重放
幂等
限流
SQL 注入
XSS
CSRF
文件上传安全
数据脱敏

尤其是：

支付
退款
账户
后台管理
删除
导出
下载
批量操作

不得只判断：

用户有没有登录

还应判断：

用户有没有权限操作这条数据

72. 文件上传

文件上传必须考虑：

文件大小
扩展名
MIME
文件内容
文件名
路径穿越
存储路径
访问权限
病毒风险

不得直接使用用户原始文件名拼接本地路径。

73. 分页接口

列表接口应考虑分页。

必须限制：

pageSize

最大值。

禁止让客户端请求：

pageSize = 1000000

导致数据库和应用内存压力。

74. 时间处理

时间字段语义必须明确。

例如：

created_time
paid_time
expired_time

涉及跨时区系统时，应明确：

数据库时区
JVM 时区
接口时区
序列化格式

不要依赖服务器默认时区。

75. AI 新增代码前检查

AI 在新增代码之前，应优先确认项目是否已经存在：

类似 Service
类似工具类
类似 DTO
类似异常
类似枚举
类似 SQL
类似配置
类似实现

如果已有能力：

优先复用，不重复创建。

76. AI 修改代码后自检

完成代码修改后，AI 应自行检查：

是否可能编译失败
import 是否正确
方法签名是否匹配
空指针
SQL 是否正确
事务是否正确
并发问题
幂等问题
数据库一致性
异常处理
日志
代码重复
变量命名
格式
安全问题
性能问题
是否影响已有接口

77. AI 生成 SQL 后自检

至少检查：

是否 SELECT *
是否可能全表扫描
索引是否合理
参数类型是否一致
是否存在 SQL 注入
是否 N+1
是否需要分页
排序是否有索引
是否可能返回巨大数据量
是否需要 EXPLAIN

78. AI 设计数据库表后自检

检查：

utf8mb4
InnoDB
id
字段类型
金额 DECIMAL
created_time
created_by
updated_time
updated_by
字段注释
表注释
索引
唯一约束
默认值
NULL 语义
字段长度

79. AI 设计接口后自检

检查：

接口职责是否单一
参数是否合法
是否应该分页
是否需要幂等
是否需要权限
是否需要限流
是否暴露 Entity
是否返回多余字段
异常码是否合理
是否兼容已有接口

80. AI 设计业务代码后自检

检查：

是否存在重复逻辑
是否超过合理方法长度
是否出现过深嵌套
是否应该拆方法
是否应该使用枚举
是否存在魔法值
是否重复查数据库
是否重复调用远程服务
是否可能并发冲突
是否可能重复执行
是否需要事务
是否需要补偿

81. AI Code Review 输出标准

如果 AI 被要求 Review 代码，问题优先级按照：

P0：严重安全 / 数据事故风险

P1：明显业务 Bug / 数据一致性 / 并发问题

P2：性能 / SQL / 可维护性问题

P3：命名 / 结构 / 代码规范问题

P4：可选优化

优先指出：

真正可能造成事故的问题

而不是把大量注意力放在：

空格
换行
个人风格

82. AI 不允许为了规范而规范

所有规范的最终目标是：

稳定
安全
清晰
高效
可维护

AI 不得机械执行规范导致：

代码更加复杂
产生过度设计
大量无意义封装
大量无意义接口
大量无意义设计模式

例如：

只有一个简单实现：

UserService

没有必要因为“面向接口”机械创建：

UserService
UserServiceImpl
AbstractUserService
BaseUserService
UserServiceFactory
UserServiceStrategy

除非架构和业务确实需要。

83. 最重要的工程思想

AI 写任何代码之前，都要考虑：

这个功能未来谁维护？

线上出问题怎么定位？

这个接口会不会重复调用？

数据库数据会不会不一致？

这个 SQL 一亿数据还能不能执行？

这个方法 QPS 1000 会发生什么？

依赖服务挂掉会发生什么？

重复消息会发生什么？

支付回调来 10 次会发生什么？

两个用户同时修改这条数据会发生什么？

代码半年以后别人还能不能看懂？

84. 最终原则

本项目拒绝：

能跑就行
先写了再说
复制粘贴
无脑堆 if
无脑加缓存
无脑加索引
无脑分布式锁
无脑设计模式
无脑微服务
无脑抽象

项目倡导：

明确业务
 ↓
明确边界
 ↓
设计数据
 ↓
设计接口
 ↓
考虑异常
 ↓
考虑并发
 ↓
考虑一致性
 ↓
考虑性能
 ↓
编写代码
 ↓
测试
 ↓
Code Review
 ↓
CI/CD

我们不是简单地“把功能写出来”。

我们是在维护一个会长期运行的工程系统。

好的代码不只是：

今天能运行

更应该：

明天能修改
半年后能读懂
业务增长后能承载
线上出事后能定位
团队其他成员能继续维护

因此，无论人还是 AI，在参与本项目开发时，都应该把自己看作：

软件工程师，而不是代码生成器。

架构决定建筑能建多高，

设计决定空间如何组织，

而编码规范决定我们砌出来的每一块砖，最终能不能形成一栋可靠、稳定、长期存在的数字建筑。