编码规范指南
通用模板。如果项目有专属技能（如 leniu-code-patterns ），优先使用。
核心规范
RESTful API 设计
操作 HTTP 方法 URL 示例 说明
创建 POST /api/v1/orders
请求体传参
查询列表 GET /api/v1/orders
Query 参数分页
查询详情 GET /api/v1/orders/{id}
路径参数
全量更新 PUT /api/v1/orders/{id}
请求体传参
部分更新 PATCH /api/v1/orders/{id}
请求体传参
删除 DELETE /api/v1/orders/{id}
路径参数
URL 规范：
-
使用名词复数：/orders 而非 /order
-
使用小写连字符：/order-items 而非 /orderItems
-
版本号放 URL 前缀：/api/v1/
-
嵌套资源不超过两层：/orders/{id}/items
命名规范
类型 风格 示例
类名 UpperCamelCase OrderService , UserController
方法名 lowerCamelCase createOrder() , getUserById()
变量名 lowerCamelCase orderNo , userName
常量 UPPER_SNAKE_CASE MAX_RETRY_COUNT , DEFAULT_PAGE_SIZE
包名 全小写 com.example.order
数据库表/字段 lower_snake_case t_order , order_no
类命名约定：
后缀 用途 示例
Controller
控制器 OrderController
Service / ServiceImpl
服务层 OrderServiceImpl
Mapper / Repository
数据访问 OrderMapper
DTO
请求参数 OrderCreateDTO
VO
响应对象 OrderVO
Enum
枚举 OrderStatusEnum
Config
配置类 RedisConfig
Handler
处理器 GlobalExceptionHandler
Interceptor
拦截器 AuthInterceptor
Utils / Helper
工具类 DateUtils
方法命名约定
前缀 含义 示例
create / add
创建 createOrder()
update / modify
更新 updateStatus()
delete / remove
删除 deleteById()
get / find / query
查询 getById() , findByName()
list
查询列表 listByStatus()
page
分页查询 pageQuery()
count
计数 countByStatus()
is / has / can
布尔判断 isValid() , hasPermission()
check / validate
校验 checkDuplicate()
convert / to
转换 convertToVO() , toDTO()
Git 提交规范（Conventional Commits）
<type>(<scope>): <subject>
<body>
<footer>
type 说明
feat
新功能
fix
修复 Bug
docs
文档变更
style
代码格式（不影响逻辑）
refactor
重构（非新功能、非修复）
perf
性能优化
test
测试相关
chore
构建/工具变更
示例：
feat(order): 新增订单导出功能
支持按时间范围导出订单数据为 Excel 格式。
Closes #123
数据类型规范
布尔语义字段必须使用 Boolean
// ❌ 错误 private Integer ifNarrow; private Integer isEnabled;
// ✅ 正确 private Boolean narrow; // getter 自动生成 isNarrow() private Boolean enabled; // getter 自动生成 isEnabled()
规则：
-
语义为"是/否"的字段，类型必须为 Boolean
-
字段名不加 if /is /has 前缀（JavaBean 规范中 Boolean 的 getter 自动生成 isXxx() ）
-
数据库字段使用 TINYINT(1) 或 BIT(1)
枚举字段必须提供明确约束
// ❌ 错误：调用方无法知道合法值 @ApiModelProperty(value = "操作类型") private Integer tradeType;
// ✅ 方案一：VO/DTO 层直接用枚举（推荐） @ApiModelProperty(value = "操作类型") private AccTradeTypeEnum tradeType;
// ✅ 方案二：保留 Integer 但标注合法值 @ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3") private Integer tradeType;
金额字段禁止使用浮点类型
// ❌ 错误 private Double amount; private Float price;
// ✅ 正确：Entity/Service 层用 Long（分），VO 层展示用 BigDecimal（元） private Long amountFen; private BigDecimal amountYuan;
原始类型 vs 包装类型
场景 用原始类型 用包装类型
Entity / VO / DTO 字段 — ✅ 统一用包装类型
方法参数（不允许 null） ✅ int count
—
方法参数（允许 null） — ✅ Integer count
局部变量 ✅ int i = 0
—
Optional 使用规范
// ❌ 错误：of() 不接受 null，value 为 null 直接 NPE Optional.of(value).orElse(defaultValue);
// ✅ 正确：ofNullable() 安全处理 null Optional.ofNullable(value).orElse(defaultValue);
// ❌ 禁止：Optional 作为方法参数或类字段 public void process(Optional<String> name) { ... } private Optional<String> name;
// ✅ 允许：Optional 作为方法返回值、链式处理 public Optional<Entity> findById(Long id) { ... } Optional.ofNullable(entity).map(Entity::getConfig).orElse(DEFAULT_VALUE);
@Transactional 规范
// ❌ 错误：默认只回滚 RuntimeException @Transactional public void createOrder() { ... }
// ✅ 正确：显式指定回滚异常 @Transactional(rollbackFor = Exception.class) public void createOrder() { ... }
-
所有 @Transactional 必须显式写 rollbackFor = Exception.class
-
只读查询不加 @Transactional （或用 readOnly = true ）
-
事务方法不要 try-catch 吞掉异常，否则事务不回滚
TODO 管理规范
// ❌ 错误：无负责人、无日期、无跟踪 // TODO 修改一下
// ✅ 正确：完整 TODO 格式 // TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
-
每个 TODO 必须有对应的任务号
-
超过 2 个迭代未处理的 TODO 必须清理
-
不用的代码直接删除，不要注释保留
代码格式化规范
项目 规范
缩进 4 个空格（不用 Tab）
行宽 120 字符
大括号 K&R 风格（同行开始）
空行 方法间 1 个空行，逻辑块间 1 个空行
import 分组排序：java → jakarta → org → net → com，组间空行
代码示例
统一响应格式
@Data @AllArgsConstructor @NoArgsConstructor public class Result<T> { private int code; private String message; private T data;
public static <T> Result<T> ok(T data) {
return new Result<>(200, "success", data);
}
public static <T> Result<T> fail(int code, String message) {
return new Result<>(code, message, null);
}
}
枚举定义规范
@Getter @AllArgsConstructor public enum OrderStatusEnum {
PENDING(0, "待处理"),
COMPLETED(1, "已完成"),
CANCELLED(2, "已取消");
private final int code;
private final String desc;
public static OrderStatusEnum of(int code) {
for (OrderStatusEnum status : values()) {
if (status.code == code) {
return status;
}
}
throw new IllegalArgumentException("未知状态码: " + code);
}
}
常见错误
错误 正确做法
URL 用动词：/getOrder
用名词 + HTTP 方法：GET /orders/{id}
方法名含义不清：process()
明确动作：calculateTotalAmount()
魔法数字：if (status == 1)
用枚举或常量
一个方法超过 80 行 拆分为多个私有方法
注释描述"做了什么" 注释描述"为什么这样做"
Git 提交信息写"fix bug" 写清楚修了什么：fix(order): 修复金额计算精度丢失
Boolean 变量名：flag
有意义的名字：isActive , hasPermission
缩写命名：usr , mgr
完整命名：user , manager
Optional.of(可能null值)
Optional.ofNullable(value)
@Transactional 无 rollbackFor @Transactional(rollbackFor = Exception.class)
TODO 无负责人和日期 // TODO(@负责人, 日期, #任务号): 描述
布尔字段用 Integer
用 Boolean 类型
枚举字段无合法值说明 @ApiModelProperty 标注合法值或直接用枚举类型