code-patterns

编码规范指南

通用模板。如果项目有专属技能（如 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

响应对象 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）

<body>

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 &#x3C;T> Result&#x3C;T> ok(T data) {
    return new Result&#x3C;>(200, "success", data);
}

public static &#x3C;T> Result&#x3C;T> fail(int code, String message) {
    return new Result&#x3C;>(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 标注合法值或直接用枚举类型

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

collaborating-with-codex

dev

leniu-code-patterns