leniu-java-code-style

leniu-tengyun-core 代码风格规范

项目特征

特征说明

包名前缀 net.xnzn.core.*

JDK 版本 21

Validation jakarta.validation.*

工具库 Hutool (CollUtil, ObjectUtil, BeanUtil)

异常类 LeException

国际化 I18n

租户上下文 TenantContextHolder

分页组件 PageHelper (PageMethod)

包结构规范

net.xnzn.core ├── [module]/ │ ├── controller/ # 控制器层 │ ├── service/ # 服务层 │ │ └── impl/ # 服务实现 │ ├── mapper/ # 数据访问层（含 XML） │ ├── model/ # 数据模型 │ │ ├── entity/ # 实体类 │ │ └── po/ # 持久化对象 │ ├── vo/ # 视图对象（返回前端） │ ├── dto/ # 数据传输对象（服务间/MQ） │ ├── param/ # 请求参数对象 │ ├── constants/ # 常量 │ ├── enums/ # 枚举 │ ├── api/ # 对外 API 接口 │ ├── config/ # 配置类 │ ├── mq/ # 消息队列监听器 │ ├── task/ # 定时任务 │ ├── handle/ # 业务处理器（策略模式） │ └── util/ # 工具类

类命名规范

类型命名格式示例

Controller XxxController

OrderController

Service 接口 XxxService

OrderService

Service 实现 XxxServiceImpl

OrderServiceImpl

Mapper XxxMapper

OrderMapper

Entity Xxx 或 XxxEntity

Order

PO XxxPO

OrderPO

VO XxxVO

OrderVO

DTO XxxDTO

OrderDTO

Param XxxParam / XxxQueryParam

OrderQueryParam

Enum XxxEnum

OrderStatusEnum

Converter XxxConverter

OrderConverter

Handler XxxHandler

OrderHandler

Api XxxApi

OrderApi

方法命名规范

操作 Service 方法 Mapper 方法 Controller URL

分页查询 pageXxx

pageXxx

GET /list

查询列表 listXxx

listXxx

查询单个 getXxx

selectById

GET /{id}

新增 save / add / create

insert

POST /

更新 update / modify

updateById

PUT /

删除 delete / remove

deleteById

DELETE /{ids}

统计 count / summary

selectCount

导出 export

POST /export

同步 sync

Controller 层模板

import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import lombok.extern.slf4j.Slf4j; import net.xnzn.core.common.exception.LeException; import net.xnzn.core.common.response.LeResponse; import net.xnzn.core.order.param.OrderQueryParam; import net.xnzn.core.order.service.OrderService; import net.xnzn.core.order.vo.OrderVO; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;

@Slf4j @RequiresAuthentication @RestController @RequestMapping("/api/order") @Api(value = "订单管理", tags = "订单管理") public class OrderController {

@Autowired
private OrderService orderService;

@ApiOperation(value = "分页查询订单")
@PostMapping("/list")
public LeResponse&#x3C;Page&#x3C;OrderVO>> list(@Valid @RequestBody OrderQueryParam param) {
    return LeResponse.success(orderService.pageList(param));
}

@ApiOperation(value = "获取订单详情")
@GetMapping("/{id}")
public LeResponse&#x3C;OrderVO> getById(@PathVariable Long id) {
    return LeResponse.success(orderService.getById(id));
}

@ApiOperation(value = "创建订单")
@PostMapping("/")
public LeResponse&#x3C;Long> create(@Valid @RequestBody OrderParam param) {
    return LeResponse.success(orderService.create(param));
}

@ApiOperation(value = "更新订单")
@PutMapping("/")
public LeResponse&#x3C;Boolean> update(@Valid @RequestBody OrderParam param) {
    return LeResponse.success(orderService.update(param));
}

@ApiOperation(value = "删除订单")
@DeleteMapping("/{ids}")
public LeResponse&#x3C;Boolean> delete(@PathVariable String ids) {
    return LeResponse.success(orderService.delete(ids));
}

}

要点：

统一使用 @PostMapping （部分查询也可以用 @GetMapping ）
需要 @RequiresAuthentication 认证注解
使用 LeResponse<T> 封装返回结果
参数校验使用 @Valid 触发

Service 层模板

import cn.hutool.core.util.ObjectUtil; import cn.hutool.core.bean.BeanUtil; import lombok.extern.slf4j.Slf4j; import net.xnzn.core.common.exception.LeException; import net.xnzn.core.order.mapper.OrderMapper; import net.xnzn.core.order.model.Order; import net.xnzn.core.order.param.OrderParam; import net.xnzn.core.order.vo.OrderVO; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Slf4j @Service public class OrderServiceImpl implements OrderService {

@Autowired
private OrderMapper orderMapper;

@Autowired
@Lazy
private ProductService productService;

@Transactional(rollbackFor = Exception.class)
public Long create(OrderParam param) {
    // 业务逻辑
    Order order = BeanUtil.copyProperties(param, Order.class);
    orderMapper.insert(order);
    return order.getId();
}

public OrderVO getById(Long id) {
    Order order = orderMapper.selectById(id);
    if (ObjectUtil.isNull(order)) {
        throw new LeException("订单不存在");
    }
    return BeanUtil.copyProperties(order, OrderVO.class);
}

public List&#x3C;OrderVO> list(OrderQueryParam param) {
    List&#x3C;Order> orders = orderMapper.selectList(buildWrapper(param));
    return BeanUtil.copyToList(orders, OrderVO.class);
}

}

要点：

使用 @Slf4j 日志注解
循环依赖使用 @Lazy
事务使用 @Transactional(rollbackFor = Exception.class)
使用 Hutool 工具类：BeanUtil 、ObjectUtil

Entity 实体类模板

import com.baomidou.mybatisplus.annotation.*; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data;

import java.time.LocalDateTime;

@Data @TableName(value = "order_table", autoResultMap = true) public class Order {

@TableId
@ApiModelProperty(value = "订单ID")
private Long id;

@ApiModelProperty(value = "用户ID")
private Long userId;

@ApiModelProperty(value = "订单金额（分）")
private Long amount;

@ApiModelProperty(value = "删除标识(1-删除,2-正常)")
private Integer delFlag;

@TableField(fill = FieldFill.INSERT)
@ApiModelProperty(value = "创建人")
private String crby;

@TableField(fill = FieldFill.INSERT)
@ApiModelProperty(value = "创建时间")
private LocalDateTime crtime;

@TableField(fill = FieldFill.INSERT_UPDATE)
@ApiModelProperty(value = "更新人")
private String upby;

@TableField(fill = FieldFill.INSERT_UPDATE)
@ApiModelProperty(value = "更新时间")
private LocalDateTime uptime;

}

要点：

使用 @TableName 指定表名
主键使用 @TableId
字段使用 @TableField 映射
审计字段：delFlag （1=删除，2=正常）、crby 、crtime 、upby 、uptime

VO/DTO 类模板

import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import jakarta.validation.constraints.*; import lombok.Data; import lombok.experimental.Accessors;

@Data @ApiModel("订单信息") @Accessors(chain = true) public class OrderVO {

@ApiModelProperty("订单ID")
private Long id;

@ApiModelProperty("用户ID")
@NotNull(message = "用户ID不能为空")
private Long userId;

@ApiModelProperty("订单金额（元）")
@NotNull(message = "订单金额不能为空")
@DecimalMin(value = "0.01", message = "金额必须大于0.01")
private BigDecimal amount;

@ApiModelProperty("订单状态")
private Integer status;

}

要点：

使用 @ApiModel 类注解
使用 @ApiModelProperty 字段注解
参数校验使用 jakarta.validation.constraints.* 注解
使用 @Accessors(chain = true) 支持链式调用

枚举类模板

import lombok.AllArgsConstructor; import lombok.Getter;

@Getter @AllArgsConstructor public enum OrderStatusEnum {

CREATED(1, "已创建"),
PAID(2, "已支付"),
COMPLETED(3, "已完成"),
CANCELLED(4, "已取消");

private final Integer key;
private final String desc;

public static OrderStatusEnum getByKey(Integer key) {
    if (key == null) {
        return null;
    }
    for (OrderStatusEnum status : values()) {
        if (status.getKey().equals(key)) {
            return status;
        }
    }
    return null;
}

public static boolean isExistKey(Integer key) {
    return getByKey(key) != null;
}

}

要点：

使用 @Getter 和 @AllArgsConstructor
提供 getByKey 静态方法
提供 isExistKey 校验方法

依赖注入规范

// 推荐：字段注入 @Autowired private OrderService orderService;

// 解决循环依赖 @Resource @Lazy private ProductService productService;

异常处理

import net.xnzn.core.common.exception.LeException; import net.xnzn.core.common.i18n.I18n;

// 简单异常 throw new LeException("订单不存在");

// 国际化异常 throw new LeException(I18n.getMessage("order.not.exists"));

// 带参数的国际化 throw new LeException(I18n.getMessage("order.status.invalid", status));

Hutool 工具类速查

import cn.hutool.core.collection.CollUtil; import cn.hutool.core.util.ObjectUtil; import cn.hutool.core.util.StrUtil; import cn.hutool.core.bean.BeanUtil;

// 集合操作 if (CollUtil.isEmpty(list)) { throw new LeException("列表不能为空"); } if (CollUtil.isNotEmpty(list)) { // 处理列表 }

// 对象判空 if (ObjectUtil.isNull(user)) { throw new LeException("用户不存在"); } if (ObjectUtil.isNotNull(user)) { // 处理用户 }

// 字符串操作 if (StrUtil.isBlank(name)) { throw new LeException("名称不能为空"); } String trimmed = StrUtil.trim(name); String joined = StrUtil.join(",", list);

// 对象拷贝 TargetDTO target = BeanUtil.copyProperties(source, TargetDTO.class); List<TargetDTO> targets = BeanUtil.copyToList(sources, TargetDTO.class);

常用注解

Jakarta Validation

重要：项目使用 JDK 21，必须使用 jakarta.validation.constraints.* 包

import jakarta.validation.Valid; import jakarta.validation.constraints.*;

@NotNull
不能为 null
@NotBlank
字符串不能为空
@NotEmpty
集合不能为空
@Valid
触发参数校验

Lombok

@Data
生成 getter/setter
@Slf4j
日志
@Builder
建造者模式
@AllArgsConstructor
全参构造
@Accessors(chain = true)
链式调用

MyBatis-Plus

@TableName
表名映射
@TableId
主键
@TableField
字段映射
@TableField(fill = FieldFill.INSERT)
插入时自动填充
@TableField(fill = FieldFill.INSERT_UPDATE)
更新时自动填充

类注释规范

推荐使用 JavaDoc 标准格式：

/**

类功能描述
@author xujiajun
@date 2026-02-20 */ public class OrderService { // ... }

说明：

@author 使用实际作者名称
@date 使用代码创建日期（格式：YYYY-MM-DD ）

常见错误

错误1：使用 RuoYi 的包名

// ❌ 错误：使用 RuoYi 的包名 package org.dromara.system.service;

// ✅ 正确：使用 leniu 的包名 package net.xnzn.core.order.service;

错误2：使用 javax.validation

// ❌ 错误：使用 javax.validation（JDK 21 应该用 jakarta） import javax.validation.constraints.NotNull;

// ✅ 正确：使用 jakarta.validation import jakarta.validation.constraints.NotNull;

错误3：使用 MapstructUtils

// ❌ 错误：使用 RuoYi 的工具类 import org.dromara.common.core.utils.MapstructUtils; Target target = MapstructUtils.convert(source, Target.class);

// ✅ 正确：leniu 使用 Hutool import cn.hutool.core.bean.BeanUtil; Target target = BeanUtil.copyProperties(source, Target.class);

错误4：使用 LeException 不使用 I18n

// ❌ 不推荐：直接硬编码中文 throw new LeException("订单不存在");

// ✅ 推荐：使用国际化 throw new LeException(I18n.getMessage("order.not.exists"));

错误5：使用 RuoYi 的 ServiceException

// ❌ 错误：使用 RuoYi 的异常 import org.dromara.common.core.exception.ServiceException;

// ✅ 正确：使用 leniu 的异常 import net.xnzn.core.common.exception.LeException;

参考文档

详见：leniu-tengyun-core 源码

leniu-java-code-style

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

dev

collaborating-with-codex

api-development

leniu-code-patterns