name: fintorq-code-style description: Official code style and development standards for the Fintorq project. MUST be followed for all Java code generation. user-invocable: true

Fintorq Code Style & Standards

This skill provides the official coding standards and development guidelines for the Fintorq project. All generated code must adhere to these rules.

1. Tech Stack & Environment

Component	Specification
Java Version	Java 17
Framework	Spring Boot 3.x
ORM	MyBatis-Plus (NOT JPA/Hibernate)
Build Tool	Gradle (Multi-module)
Utils	Lombok (Heavy usage), Hutool
Logging	SLF4J
API Doc	Knife4j/OpenAPI 3
Security	Spring Security + JWT

2. Project Structure & Package Organization

Module Organization

com.fintorq.*
├── {module}center/        # 模块名 (loancenter, usercenter, cmcenter 等)
│   ├── controller/        # 控制器
│   ├── service/           # 服务接口
│   ├── service/impl/      # 服务实现
│   ├── mapper/            # 数据访问
│   ├── entity/            # 实体类 (PO)
│   │   ├── po/            # 持久化对象
│   │   ├── dto/           # 数据传输对象
│   │   ├── vo/            # 视图对象
│   │   ├── req/           # 请求对象
│   │   └── resp/          # 响应对象
│   └── constants/         # 常量定义

Module Name Conventions

模块	Package Name
贷款模块	`loancenter`
用户模块	`usercenter`
通用模块	`cmcenter`
合作伙伴模块	`partnercenter`

3. Naming Conventions

Class Naming

类型	命名规范	示例
Controller	`{Name}Controller`	`LoanQuoteLeadController`
Service Interface	`I{Name}Service`	`ILoanQuoteLeadService`
Service Implementation	`{Name}ServiceImpl`	`LoanQuoteLeadServiceImpl`
Mapper	`{Name}Mapper`	`LoanQuoteLeadMapper`
Entity/PO	`{Name}`	`LoanQuoteLead`
DTO	`{Name}DTO`	`DashboardDTO`
VO	`{Name}VO`	`LoanQuoteLeadVO`
Req	`{Name}Req`	`LoanQuoteLeadListReq`
Resp	`{Name}Resp`	`DashboardResp`
Config	`{Name}Config`	`ThreadPoolConfig`
Enum	`{Name}Enum`	`LoanQuoteLeadStatusEnum`

Method/Variable Naming

类型	规范	示例
Methods	lowerCamelCase	`getUserById`, `saveLoanQuoteLead`
Variables	lowerCamelCase	`userId`, `loanQuoteLead`
Constants	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE`
Boolean Methods	Prefix with `is`, `has`, `can`	`isValid()`, `hasPermission()`

4. Architectural Layers & Class Types

4.1 Controller Layer

职责: 处理 HTTP 请求，参数验证，调用 Service 层，返回响应

必需注解:

@Slf4j
@Tag(name = "模块名称", description = "模块描述")
@RestController
@RequestMapping("/path")  // lowerCamelCase
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class ExampleController {

    private final IExampleService exampleService;
}

权限控制:

@PreAuthorize("hasAuthority('permission.code')")

返回类型:

有数据: Result<T>
无数据: void (直接写入 response)
分页: Result<CommonPageResp<T>>

完整示例:

@Slf4j
@Tag(name = "贷款报价线索管理模块", description = "贷款报价前端信息管理相关接口")
@RestController
@RequestMapping("/loanQuoteLead")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class LoanQuoteLeadController {

    private final ILoanQuoteLeadService loanQuoteLeadService;

    /**
     * 分页查询贷款报价线索列表
     *
     * @param req 查询条件
     * @return 分页结果
     */
    @PostMapping("/getLoanQuoteLeadList")
    @Operation(summary = "分页查询贷款报价线索列表")
    @PreAuthorize("hasAuthority('worklist.read')")
    public Result<CommonPageResp<LoanQuoteLeadListResp>> getLoanQuoteLeadList(
            @Parameter(description = "查询条件", required = true)
            @Valid @RequestBody LoanQuoteLeadListReq req) {

        log.info("查询贷款报价线索列表，操作人：{}，查询条件：{}",
                RequestContext.getUserId(), req);

        IPage<LoanQuoteLeadVO> voPage = loanQuoteLeadService.getLoanQuoteLeadList(req);
        IPage<LoanQuoteLeadListResp> respPage = voPage.convert(LoanQuoteLeadListResp::toResp);
        CommonPageResp<LoanQuoteLeadListResp> result = CommonPageResp.toCommonPageResp(respPage);

        return Result.success(result);
    }
}

4.2 Service Layer

接口定义:

public interface ILoanQuoteLeadService extends IService<LoanQuoteLead> {
    SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto);
    IPage<LoanQuoteLeadVO> getLoanQuoteLeadList(LoanQuoteLeadListReq req);
}

实现类:

@Slf4j
@Service
@RequiredArgsConstructor
public class LoanQuoteLeadServiceImpl extends ServiceImpl<LoanQuoteLeadMapper, LoanQuoteLead>
        implements ILoanQuoteLeadService {

    private final ILoanQuoteLeadNoteService loanQuoteLeadNoteService;

    @Value("${sla.default}")
    private int slaHours;

    @Override
    @Transactional(rollbackFor = Exception.class)
    public SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(
            @NotNull SaveOrUpdateLoanQuoteLeadDTO dto) {
        // 业务逻辑
    }
}

依赖注入规范:

使用 @RequiredArgsConstructor (Lombok)
不使用 onConstructor = @__(@Autowired) (Service 层可省略)
注入字段使用 private final

4.3 Mapper Layer

接口定义:

@Mapper
public interface LoanQuoteLeadMapper extends BaseMapper<LoanQuoteLead> {

    IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadDbVO> page,
                                                     @Param("dto") LoanQuoteLeadListDBDTO dto);
}

XML 映射文件位置: src/main/resources/mapper/{module}/

4.4 Entity/PO Layer

实体类规范:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@TableName("t_loan_quote_lead")
public class LoanQuoteLead extends BaseCommonPO {

    @TableId(type = IdType.AUTO)
    private Long id;

    @TableField("mobile")
    private String mobile;

    @TableField("organization_code")
    private String organizationCode;

    // BaseCommonPO 包含: createTime, updateTime, createBy, updateBy, deleteFlag
}

字段规范:

使用 @TableName 指定表名
使用 @TableId(type = IdType.AUTO) 主键
使用 @TableField 映射数据库字段
继承 BaseCommonPO 获取通用字段

4.5 Data Transfer Objects (Req/DTO/VO/Resp)

对象职责划分:

类型	职责	示例
Req	接收前端请求参数	`LoanQuoteLeadListReq`
DTO	Service 层内部数据传输	`DashboardDTO`
VO	Service 层返回给 Controller	`LoanQuoteLeadVO`
Resp	返回给前端	`DashboardResp`

示例:

// Req - 接收请求参数
@Data
public class LoanQuoteLeadListReq {
    @NotNull(message = "页码不能为空")
    private Integer current;

    @NotNull(message = "页大小不能为空")
    private Integer size;

    private String searchText;
    private Integer timeRangeFilter;
}

// DTO - 内部数据传输
@Data
public class DashboardDTO {
    private String timePeriod;
}

// VO - Service 层返回
@Data
public class LoanQuoteLeadVO {
    private Long id;
    private String mobile;
    private Integer status;
}

// Resp - 返回给前端
@Data
public class DashboardResp {
    private Integer naf;
    private BigDecimal potentialSales;
}

4.6 【强制】分层架构数据类型约束

严格遵循各层的数据类型规范，确保清晰的职责边界和数据流向。

4.6.1 Controller 层约束

方法入参类型：

✅ 允许：基本类型参数（Long id, String code 等）
✅ 允许：Req 对象
❌ 禁止：DTO、VO、DbVO、Resp 对象

方法返回值类型：

✅ 允许：基本类型参数
✅ 允许：Resp 对象（通过 Result<Resp> 包装）
❌ 禁止：DTO、VO、DbVO、Req 对象

示例：

// ✅ 正确 - 使用 Req 入参，Resp 返回值
@PostMapping("/getLoanQuoteLeadList")
public Result<CommonPageResp<LoanQuoteLeadListResp>> getLoanQuoteLeadList(
        @Valid @RequestBody LoanQuoteLeadListReq req) {
    IPage<LoanQuoteLeadVO> voPage = loanQuoteLeadService.getLoanQuoteLeadList(req);
    IPage<LoanQuoteLeadListResp> respPage = voPage.convert(LoanQuoteLeadListResp::toResp);
    return Result.success(CommonPageResp.toCommonPageResp(respPage));
}

// ❌ 错误 - Controller 不应直接返回 VO
public Result<IPage<LoanQuoteLeadVO>> getLoanQuoteLeadList(LoanQuoteLeadListReq req) {
    return Result.success(loanQuoteLeadService.getLoanQuoteLeadList(req));
}

// ❌ 错误 - Controller 不应接收 DTO
public Result<Resp> method(Dto dto) {
    // ...
}

4.6.2 Service 层约束

方法入参类型：

✅ 允许：基本类型参数
✅ 允许：DTO 对象、Req 对象
❌ 禁止：VO、DbVO、Resp 对象

方法返回值类型：

✅ 允许：基本类型参数
✅ 允许：VO 对象
❌ 禁止：DTO、DbVO、Resp、Req 对象

示例：

// ✅ 正确 - 使用 DTO 入参，VO 返回值
public interface ILoanQuoteLeadService extends IService<LoanQuoteLead> {
    SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto);
    IPage<LoanQuoteLeadVO> getLoanQuoteLeadList(LoanQuoteLeadListReq req);
}

// ❌ 错误 - Service 不应返回 DTO
public SaveOrUpdateLoanQuoteLeadDTO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto) {
    // ...
}

// ❌ 错误 - Service 不应直接返回 DbVO
public IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(LoanQuoteLeadListReq req) {
    // ...
}

4.6.3 Mapper 层约束

方法入参类型：

✅ 允许：基本类型参数
✅ 允许：DTO 对象（需加 @Param("dto") 注解）
❌ 禁止：Req、VO、DbVO、Resp 对象

方法返回值类型：

✅ 允许：基本类型参数
✅ 允许：DbVO 对象
❌ 禁止：DTO、VO、Resp、Req 对象

示例：

// ✅ 正确 - 使用 DTO 入参，DbVO 返回值
@Mapper
public interface LoanQuoteLeadMapper extends BaseMapper<LoanQuoteLead> {
    IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadDbVO> page,
                                                   @Param("dto") LoanQuoteLeadListDBDTO dto);
}

// ❌ 错误 - Mapper 不应返回 VO
IPage<LoanQuoteLeadVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadVO> page,
                                            @Param("dto") LoanQuoteLeadListDBDTO dto);

// ❌ 错误 - Mapper 不应接收 Req
IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadDbVO> page,
                                              @Param("req") LoanQuoteLeadListReq req);

4.6.4 数据流向图

┌─────────────────────────────────────────────────────────────────┐
│                        数据流向                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Frontend                                                       │
│     │                                                           │
│     │ ① Req                                                     │
│     ▼                                                           │
│  ┌─────────────┐                                               │
│  │ Controller  │                                               │
│  │  ─────────  │   ② DTO/Req                                   │
│  │     │       │ ───────────────────────┐                       │
│  └─────────────┘                       │                       │
│       │                                 │                       │
│       │ ③ VO                            ▼                       │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐          │
│  │   (convert) │   │   Service   │   │   Mapper    │          │
│  │  ─────────  │   │  ─────────  │   │  ─────────  │          │
│  │      │      │   │     │       │   │     │       │          │
│  │      │      │   └─────────────┘   └─────────────┘          │
│  │      │      │         │                 │                   │
│  │      │      │         │ ④ DTO           │ ⑤ DbVO            │
│  │      │      │         │ ─────────────── │ ───────────────┐  │
│  │      ▼      │         │                 │                │  │
│  │  ┌───────┐  │         │                 ▼                ▼  │
│  │  │ Resp  │  │         │           ┌─────────────┐   ┌─────────────┐
│  │  └───────┘  │         │           │  Database   │   │  Database   │
│  │             │         │           └─────────────┘   └─────────────┘
│  └─────────────┘         │
│       │                 │
│       │ ⑥ Resp                                                     │
│       ▼                                                           │
│  Frontend                                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

数据类型用途说明：

类型	使用场景	可出现层次
Req	接收前端请求参数	Controller → Service
Resp	返回数据给前端	Controller
DTO	Service 层内部数据传输	Service ↔ Mapper
VO	Service 层业务数据封装	Service → Controller
DbVO	数据库查询结果封装	Mapper → Service

5. Dependency Injection & Configuration

5.1 依赖注入方式

推荐方式: @RequiredArgsConstructor

@Service
@RequiredArgsConstructor
public class ExampleServiceImpl {

    private final IExampleService exampleService;
    private final IOrgFacadeService orgFacadeService;
}

Controller 层: 可添加 onConstructor = @__(@Autowired)

@RequiredArgsConstructor(onConstructor = @__(@Autowired))

5.2 配置类规范

命名: {Name}Config

示例:

@Configuration
@EnableDataPermission
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        // 配置
    }
}

6. API Design Standards

6.1 REST API 路径设计

规范:

使用 lowerCamelCase (小驼峰)
名词复数表示资源集合
使用 HTTP 方法语义

示例:

POST   /api/loanQuoteLead/getLoanQuoteLeadList
POST   /api/loanQuoteLead/saveOrUpdate
POST   /api/loanQuoteLead/addNote
POST   /api/loanQuoteLead/export

6.2 输入验证与安全

对所有外部输入进行严格验证和清洗:

@Data
public class LoanQuoteLeadListReq {
    @NotNull(message = "页码不能为空")
    @Min(value = 1, message = "页码必须大于0")
    private Integer current;

    @NotNull(message = "页大小不能为空")
    @Min(value = 1, message = "页大小必须大于0")
    @Max(value = 100, message = "页大小不能超过100")
    private Integer size;

    @Pattern(regexp = "^$|^[A-Za-z0-9]+$", message = "搜索文本只能包含字母和数字")
    private String searchText;
}

安全原则:

使用 @Valid 或 @Validated 触发验证
使用 @PreAuthorize 进行权限控制
防止 SQL 注入：使用 MyBatis-Plus 参数绑定
防止 XSS：对用户输入进行编码
敏感数据（密码、密钥）不在日志中明文输出

敏感数据日志安全:

// ❌ 错误 - 密码明文输出
log.info("User login: username={}, password={}", username, password);

// ✅ 正确 - 不记录敏感信息
log.info("User login attempt: username={}", username);

// ✅ 正确 - 脱敏处理
log.info("User login: username={}, password=****", username);

6.3 权限控制

使用 @PreAuthorize 注解:

@PreAuthorize("hasAuthority('worklist.read')")
@PreAuthorize("hasAuthority('worklist.write')")
@PreAuthorize("hasAuthority('dashboard')")
@PreAuthorize("hasAuthority('report')")

权限码位置: com.fintorq.common.core.enums.auth.PermissionCodeEnum

6.4 Swagger 文档注解

@Tag(name = "模块名称", description = "模块描述")
@Operation(summary = "接口摘要", description = "详细描述")
@Parameter(description = "参数描述", required = true)

7. Data Access Standards

7.1 MyBatis-Plus 使用规范

基础 CRUD: 使用 IService 和 ServiceImpl 提供的方法

// 查询单个
LoanQuoteLead lead = this.getById(leadId);

// 查询列表
List<LoanQuoteLead> leads = this.list();

// 保存
boolean success = this.save(loanQuoteLead);

// 更新
boolean success = this.updateById(loanQuoteLead);

// 删除
boolean success = this.removeById(leadId);

复杂查询: 自定义 Mapper 方法

// Mapper
IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadDbVO> page,
                                               @Param("dto") LoanQuoteLeadListDBDTO dto);

// Service
Page<LoanQuoteLeadDbVO> page = new Page<>(req.getCurrent(), req.getSize());
IPage<LoanQuoteLeadDbVO> result = baseMapper.getLoanQuoteLeadPage(page, dbDto);

7.2 枚举规范

实现 IEnum<T> 接口:

public enum LoanQuoteLeadStatusEnum implements IEnum<Integer> {

    NEW(1, "New"),
    CONTACTED(2, "Contacted"),
    IN_PROGRESS(3, "In Progress"),
    COMPLETED(4, "Completed"),
    LOST(5, "Lost");

    private final Integer id;
    private final String name;

    LoanQuoteLeadStatusEnum(Integer id, String name) {
        this.id = id;
        this.name = name;
    }

    @Override
    public Integer getId() {
        return this.id;
    }

    @Override
    public String getName() {
        return this.name;
    }

    public static LoanQuoteLeadStatusEnum toEnum(int id) {
        return Arrays.stream(values())
                .filter(e -> e.getId().equals(id))
                .findFirst()
                .orElse(null);
    }

    public static String getNameById(Integer id) {
        if (id == null) {
            return null;
        }
        LoanQuoteLeadStatusEnum statusEnum = toEnum(id);
        return statusEnum != null ? statusEnum.getName() : null;
    }
}

7.3 数据权限

使用 @EnableDataPermission 注解启用数据权限:

@EnableDataPermission
IPage<LoanQuoteLeadDbVO> getLoanQuoteLeadPage(Page<LoanQuoteLeadDbVO> page,
                                               @Param("dto") LoanQuoteLeadListDBDTO dto);

组织权限隔离: 在查询 DTO 中设置 organizationCode

dbDto.setOrganizationCode(RequestContext.getCurrentUserOrgCode());

8. Exception Handling & Response Format

8.1 异常码体系

位置: com.fintorq.common.core.enums.ExceptionCodeEnum

分类:

2xx: 成功状态码
3xx: 重定向状态码
4xx: 客户端错误状态码
5xx: 服务器错误状态码
- 5001xx: 通用请求参数、业务数据异常
- 5003xx: common service error
- 5005xx: loan service error

常用异常码:

SUCCESS(200, "OK")
PARAM_MISS(500101, "Request param is missing")
PARAM_ERROR(500102, "Request param error")
DATA_NOT_EXIST(500103, "Data does not exist")
DATA_ALREADY_EXISTS(500104, "Data already exists")
SERVER_ERROR(500, "Internal server error")

8.2 异常抛出

使用 BusinessException:

throw new BusinessException(ExceptionCodeEnum.PARAM_MISS, "Organization code cannot be empty!");
throw new BusinessException(ExceptionCodeEnum.DATA_NOT_EXIST,
        String.format("Organization not found for code: %s", orgCode));

8.3 统一响应格式

成功响应:

return Result.success(data);

分页响应:

CommonPageResp<T> result = CommonPageResp.toCommonPageResp(page);
return Result.success(result);

无返回值:

public void exportData(@Valid @RequestBody ExportReq req, HttpServletResponse response) {
    // 直接写入 response
}

9. Coding Standards

9.1 空值处理

尽量避免返回 null:

对于可能为空的返回值，使用 Optional<T> 明确表达（Java 8+）
方法参数若不允许 null，使用 Objects.requireNonNull 检查

// ✅ 推荐 - 使用 Optional
public Optional<User> findUserById(Long id) {
    User user = userMapper.selectById(id);
    return Optional.ofNullable(user);
}

// ✅ 推荐 - 参数非空检查
public void setName(String name) {
    this.name = Objects.requireNonNull(name, "name 不能为空");
}

// ✅ 推荐 - 集合返回空集合而非 null
public List<LoanQuoteLead> getLeadsByStatus(Integer status) {
    List<LoanQuoteLead> leads = baseMapper.selectList(
        new QueryWrapper<LoanQuoteLead>().eq("status", status)
    );
    return CollUtil.isEmpty(leads) ? Collections.emptyList() : leads;
}

// ❌ 避免 - 返回 null
public List<LoanQuoteLead> getLeadsByStatus(Integer status) {
    List<LoanQuoteLead> leads = baseMapper.selectList(...);
    return leads.isEmpty() ? null : leads;  // 不推荐
}

9.2 线程安全

优先设计无状态或不可变的类，这样可天然支持并发。

对于共享可变状态，必须使用合适的并发控制:

// ✅ 推荐 - 无状态 Service（天然线程安全）
@Service
@RequiredArgsConstructor
public class LoanQuoteLeadServiceImpl {
    // 只有 final 字段，无共享可变状态
    private final LoanQuoteLeadMapper mapper;
}

// ✅ 推荐 - 使用线程安全集合
@Component
public class CacheManager {
    private final ConcurrentHashMap<String, Object> cache = new ConcurrentHashMap<>();
}

// ✅ 推荐 - 使用原子类
@Component
public class CounterService {
    private final AtomicLong counter = new AtomicLong(0);

    public long increment() {
        return counter.incrementAndGet();
    }
}

// ✅ 推荐 - 使用 volatile 保证可见性
@Component
public class ConfigHolder {
    private volatile String configValue;

    public void updateConfig(String value) {
        this.configValue = value;
    }
}

// ⚠️ 谨慎使用 - synchronized 方法
@Component
public class LegacySyncService {
    private final Object lock = new Object();

    public void criticalSection() {
        synchronized (lock) {
            // 临界区代码
        }
    }
}

9.3 异常安全与资源管理

使用 try-with-resources 管理可关闭资源:

// ✅ 推荐 - try-with-resources
public void processFile(String path) {
    try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
        // 处理文件
    } catch (IOException e) {
        log.error("Failed to process file: {}", path, e);
        throw new BusinessException(ExceptionCodeEnum.SERVER_ERROR, "文件处理失败");
    }
}

// ❌ 避免 - 手动关闭资源
public void processFile(String path) {
    BufferedReader reader = null;
    try {
        reader = new BufferedReader(new FileReader(path));
        // 处理文件
    } catch (IOException e) {
        // ...
    } finally {
        if (reader != null) {
            try {
                reader.close();  // 容易遗漏
            } catch (IOException e) {
                // ...
            }
        }
    }
}

确保异常时资源不会泄露:

// ✅ 正确 - 异常时资源自动释放
@Transactional(rollbackFor = Exception.class)
public void processWithJdbc(DataSource dataSource) {
    try (Connection conn = dataSource.getConnection();
         PreparedStatement stmt = conn.prepareStatement("SELECT * FROM t_table")) {
        // 处理数据库操作
    } catch (SQLException e) {
        log.error("Database error", e);
        throw new BusinessException(ExceptionCodeEnum.SERVER_ERROR, "数据库操作失败");
    }
}

9.4 注释规范

类级别 Javadoc:

/**
 * 贷款报价线索服务实现类
 *
 * @author ratio
 * @since 2025/11/26
 */

方法级别 Javadoc:

/**
 * 发送已提交的邮件
 *
 * @param dto 包含贷款报价线索数据的 DTO对象
 */
private void sendSubmittedEmail(SaveOrUpdateLoanQuoteLeadDTO dto, LoanQuoteLead loanQuoteLead) {
    // 实现
}

字段注释:

/**
 * SLA超时时间（小时）
 * 从配置文件读取，支持动态调整
 */
@Value("${sla.default}")
private int slaHours;

9.5 健壮原则

编写健壮的代码，对边界值和异常输入要有明确处理逻辑：

// ✅ 推荐 - 边界值检查
public void setPageSize(int pageSize) {
    if (pageSize < 1 || pageSize > 1000) {
        throw new IllegalArgumentException(
            String.format("页大小必须在 1-1000 之间，当前值: %d", pageSize)
        );
    }
    this.pageSize = pageSize;
}

// ✅ 推荐 - 对外部数据进行验证
public void processExternalData(ExternalDataDto dto) {
    if (dto == null) {
        throw new BusinessException(ExceptionCodeEnum.PARAM_MISS, "外部数据不能为空");
    }

    // 验证关键字段
    if (StrUtil.isBlank(dto.getId())) {
        throw new BusinessException(ExceptionCodeEnum.PARAM_ERROR, "ID 不能为空");
    }

    // 安全处理集合
    List<String> items = dto.getItems() != null ? dto.getItems() : Collections.emptyList();

    // 继续处理...
}

// ✅ 推荐 - 使用默认值而非 null
public String getConfigValue(String key) {
    String value = configService.get(key);
    return StrUtil.blankToDefault(value, "default");
}

9.6 注释规范

类型	是否必须写 Javadoc	说明
IService 接口	✅ 必须	所有 public 方法必须写 Javadoc
Mapper 接口	✅ 必须	所有方法必须写 Javadoc
ServiceImpl 实现类	⚠️ 条件必须	见下方详细规则
Controller 类	✅ 必须	所有 public 方法必须写 Javadoc
私有方法	✅ 必须	实现类中的私有方法必须写 Javadoc

ServiceImpl Javadoc 规则:

public class LoanQuoteLeadServiceImpl implements ILoanQuoteLeadService {

    // ✅ 不需要写 Javadoc - 接口已有定义
    @Override
    public SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto) {
        // 实现
    }

    // ✅ 必须写 Javadoc - 这是私有方法，接口中没有定义
    /**
     * 发送已提交的邮件
     *
     * @param dto 包含贷款报价线索数据的 DTO对象
     * @param loanQuoteLead 贷款报价线索实体
     */
    private void sendSubmittedEmail(SaveOrUpdateLoanQuoteLeadDTO dto, LoanQuoteLead loanQuoteLead) {
        // 实现
    }

    // ✅ 必须写 Javadoc - 这是 protected 方法，接口中没有定义
    /**
     * 构建经销商邮件模板变量
     *
     * @param dto 贷款报价线索 DTO
     * @param orgFacadeVO 组织信息
     * @return 模板变量 Map
     */
    protected Map<String, String> buildDealerEmailTemplateVariables(
            SaveOrUpdateLoanQuoteLeadDTO dto, OrgFacadeVO orgFacadeVO) {
        // 实现
    }
}

IService/Mapper 接口示例:

/**
 * 贷款报价线索服务接口
 *
 * @author ratio
 * @since 2025/11/26
 */
public interface ILoanQuoteLeadService extends IService<LoanQuoteLead> {

    /**
     * 保存或更新贷款报价线索
     *
     * @param dto 贷款报价线索数据传输对象
     * @return 保存或更新后的视图对象
     */
    SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto);

    /**
     * 分页查询贷款报价线索列表
     *
     * @param req 查询请求参数
     * @return 分页结果
     */
    IPage<LoanQuoteLeadVO> getLoanQuoteLeadList(LoanQuoteLeadListReq req);
}

9.7 日志规范

使用 @Slf4j 注解:

@Slf4j
public class ExampleService {
    // 使用 log
}

日志格式:

// Info 级别 - 记录关键操作
log.info("查询贷款报价线索列表，操作人：{}，查询条件：{}",
        RequestContext.getUserId(), req);

log.info("查询贷款报价线索列表完成，返回{}条记录，当前页：{}，每页大小：{}，总记录数：{}",
        result.getList().size(), result.getPageNum(), result.getPageSize(), result.getTotal());

// Warn 级别 - 记录警告
log.warn("Loan quote lead not found for update: id={}", dto.getId());

// Error 级别 - 记录错误
log.error("Failed to save loan quote lead: id={}", dto.getId());
log.error("Failed to send dealer notice email for lead id {} and organization {}: {}",
        dto.getId(), organizationCode, e.getMessage(), e);

日志占位符: 使用 {} 而非字符串拼接

9.8 工具类使用

Hutool 工具类:

// 字符串工具
StrUtil.isEmpty(str)
StrUtil.isNotBlank(str)
StrUtil.blankToDefault(str, defaultValue)

// Bean 工具
BeanUtil.copyProperties(source, target)

// 集合工具
CollUtil.isNotEmpty(list)

时间处理:

// 使用 java.time API
Instant.now()
LocalDateTime.now()
Date.from(instant)

11. Testing Standards

11.1 测试类命名

命名规范: {ClassName}Test

示例:

class QuotationServiceImplSimpleTest {
    // 测试方法
}

11.2 测试注解

@ExtendWith(MockitoExtension.class)  // JUnit 5 + Mockito
@DisplayName("测试描述")

11.3 Mock 规范

@Mock
private QuotationMapper quotationMapper;

@Mock
private IApplicationService applicationService;

@InjectMocks
@Spy
private QuotationServiceImpl quotationService;

静态方法 Mock:

try (MockedStatic<RequestContext> mockedRequestContext = mockStatic(RequestContext.class)) {
    mockedRequestContext.when(RequestContext::getUserId).thenReturn(1001L);
    // 测试逻辑
}

11.4 测试方法命名

推荐格式: {methodName}_{scenario}_{expectedResult}

示例:

@Test
@DisplayName("批量创建quotation - 基本功能测试")
void testBatchCreateQuotations_BasicFunctionality() {
    // Given
    // When
    // Then
}

@Test
@DisplayName("批量创建quotation - 空列表测试")
void testBatchCreateQuotations_EmptyList() {
    // 测试
}

@Test
@DisplayName("批量创建quotation - null列表测试")
void testBatchCreateQuotations_NullList() {
    // 测试
}

11.5 断言规范

// 使用 JUnit 5 Assertions
assertNotNull(result);
assertEquals(1, result.size());
assertTrue(result.containsKey("PEPPER"));

// 异常断言
BusinessException exception = assertThrows(BusinessException.class, () -> {
    quotationService.selectQuotation(applicationId, quotationId);
});
assertEquals("Application does not exist or has been deleted", exception.getMessage());

12. Common Patterns

12.1 分页查询模式

@Override
public IPage<LoanQuoteLeadVO> getLoanQuoteLeadList(LoanQuoteLeadListReq req) {
    // 1. 转换查询条件
    LoanQuoteLeadListDBDTO dbDto = convertToDBDTO(req);

    // 2. 创建分页对象
    Page<LoanQuoteLeadDbVO> page = new Page<>(req.getCurrent(), req.getSize());

    // 3. 执行查询
    IPage<LoanQuoteLeadDbVO> dbResult = baseMapper.getLoanQuoteLeadPage(page, dbDto);

    // 4. 转换为 VO
    return new Page<>(req.getCurrent(), req.getSize(), dbResult.getTotal()) {
        {
            setRecords(dbResult.getRecords().stream()
                    .map(this::convertToVO)
                    .collect(Collectors.toList()));
        }
    };
}

12.2 保存/更新模式

@Override
public SaveOrUpdateLoanQuoteLeadVO saveOrUpdateLoanQuoteLead(SaveOrUpdateLoanQuoteLeadDTO dto) {
    if (dto.getId() != null) {
        // 更新现有记录
        LoanQuoteLead entity = this.getById(dto.getId());
        if (entity == null) {
            throw new BusinessException(ExceptionCodeEnum.DATA_NOT_EXIST);
        }
        BeanUtil.copyProperties(dto, entity);
        this.updateById(entity);
        return new SaveOrUpdateLoanQuoteLeadVO(entity);
    } else {
        // 创建新记录
        LoanQuoteLead entity = new LoanQuoteLead();
        BeanUtil.copyProperties(dto, entity);
        entity.setCreateTime(new Date());
        this.save(entity);
        return new SaveOrUpdateLoanQuoteLeadVO(entity);
    }
}

12.3 异步操作模式

// 异步发送邮件
CompletableFuture.runAsync(() -> sendThankNoticeEmailToCUser(dto),
        threadPoolManager.getEmailSendThreadPoolExecutor()
).exceptionally(throwable -> {
    log.error("Failed to send email for mobile: {}", dto.getMobile(), throwable);
    return null;
});

13. Important Notes

13.1 禁止事项

NO JPA Annotations: 不使用 javax.persistence 或 jakarta.persistence 注解
NO @Autowired on fields: 不使用字段注入
NO System.out/err: 使用日志框架
NO raw types: 使用泛型
NO deprecated Date: 使用 java.time API

13.2 时区处理

数据库时间存储: UTC
客户端时区: 通过 RequestContext.getTimeZone() 获取
时间转换: 使用 ZoneOffset.UTC

13.3 敏感数据过滤

根据用户权限和数据状态动态过滤敏感字段（如 overdue 订单的姓名、邮箱、电话）。

private boolean hasViewOverdueSensitiveDataPermission() {
    return RequestContext.hasAuthority(PermissionCodeEnum.VIEW_OVERDUE_LEAD.getName());
}

14. AI 代码生成指引

本章节为 AI 代码生成提供指导原则，确保生成的代码具有高质量、可维护性和可扩展性。

14.1 可读性与清晰性

优先考虑代码的清晰和可读性：

// ✅ 推荐 - 清晰直观
public List<LoanQuoteLead> getActiveLeads() {
    return baseMapper.selectList(
        new QueryWrapper<LoanQuoteLead>().eq("status", Status.ACTIVE)
    );
}

// ❌ 避免 - 过度"巧妙"但晦涩
public List<LoanQuoteLead> getActiveLeads() {
    return Stream.of(baseMapper.selectList(null))
        .filter(l -> Status.ACTIVE.equals(l.getStatus()))
        .collect(Collectors.toList());
}

生成的代码要自解释：

使用有意义的变量名和方法名
避免单字母变量名（除循环变量 i、j 等）
命名要准确反映其用途

14.2 单一职责原则

函数、方法和类应尽量职责单一，功能内聚：

// ✅ 推荐 - 单一职责
@Service
@RequiredArgsConstructor
public class LoanQuoteLeadServiceImpl {

    public SaveOrUpdateLoanQuoteLeadVO saveOrUpdate(SaveOrUpdateLoanQuoteLeadDTO dto) {
        validateDto(dto);           // 验证
        LoanQuoteLead entity = convertToEntity(dto);  // 转换
        saveEntity(entity);          // 保存
        sendNotification(entity);    // 通知
        return convertToVO(entity);
    }

    private void validateDto(SaveOrUpdateLoanQuoteLeadDTO dto) {
        // 验证逻辑
    }

    private LoanQuoteLead convertToEntity(SaveOrUpdateLoanQuoteLeadDTO dto) {
        // 转换逻辑
    }

    private void sendNotification(LoanQuoteLead entity) {
        // 通知逻辑
    }
}

// ❌ 避免 - 一个方法做太多事情
public SaveOrUpdateLoanQuoteLeadVO saveOrUpdate(SaveOrUpdateLoanQuoteLeadDTO dto) {
    // 100+ 行代码，包含验证、转换、保存、通知等多种职责
}

14.3 避免重复与简单优先

遵循 DRY（Don't Repeat Yourself）原则：

// ✅ 推荐 - 提取公共方法
private void applyCommonFilters(QueryWrapper<LoanQuoteLead> wrapper, SearchReq req) {
    if (StrUtil.isNotBlank(req.getMobile())) {
        wrapper.like("mobile", req.getMobile());
    }
    if (StrUtil.isNotBlank(req.getOrganizationCode())) {
        wrapper.eq("organization_code", req.getOrganizationCode());
    }
}

// ❌ 避免 - 重复代码
public List<LoanQuoteLead> search1(SearchReq req) {
    QueryWrapper<LoanQuoteLead> wrapper = new QueryWrapper<>();
    if (StrUtil.isNotBlank(req.getMobile())) {
        wrapper.like("mobile", req.getMobile());
    }
    // ...
}

public List<LoanQuoteLead> search2(SearchReq req) {
    QueryWrapper<LoanQuoteLead> wrapper = new QueryWrapper<>();
    if (StrUtil.isNotBlank(req.getMobile())) {
        wrapper.like("mobile", req.getMobile());
    }
    // ...
}

保持代码简单直接（KISS 原则）：

满足需求的前提下选用简单可维护的方案
不必追求过度抽象或极致优化，除非明确必要

14.4 可维护性和扩展性

鼓励使用接口和抽象来解耦模块：

// ✅ 推荐 - 面向接口编程
@Service
@RequiredArgsConstructor
public class LoanQuoteLeadServiceImpl implements ILoanQuoteLeadService {

    private final LoanQuoteLeadMapper mapper;          // 接口注入
    private final INotificationService notificationService;  // 接口注入
}

// ❌ 避免 - 紧耦合设计
@Service
public class LoanQuoteLeadServiceImpl {

    private LoanQuoteLeadMapper mapper = new LoanQuoteLeadMapper();  // 硬编码创建
}

遵循 SOLID 等设计原则：

Single Responsibility：单一职责
Open/Closed：对扩展开放，对修改封闭
Liskov Substitution：里氏替换
Interface Segregation：接口隔离
Dependency Inversion：依赖倒置

14.5 错误处理与日志

生成具有意义的错误信息：

// ✅ 推荐 - 具体的错误信息
if (StrUtil.isBlank(dto.getMobile())) {
    throw new BusinessException(
        ExceptionCodeEnum.PARAM_ERROR,
        "手机号不能为空"
    );
}

if (!isValidMobile(dto.getMobile())) {
    throw new BusinessException(
        ExceptionCodeEnum.PARAM_ERROR,
        String.format("手机号格式不正确: %s", dto.getMobile())
    );
}

// ❌ 避免 - 模糊的错误信息
if (StrUtil.isBlank(dto.getMobile())) {
    throw new BusinessException(ExceptionCodeEnum.PARAM_ERROR, "参数错误");
}

避免吞掉异常：

// ✅ 推荐 - 记录并重新抛出
try {
    sendEmail(dto);
} catch (EmailException e) {
    log.error("Failed to send email for mobile: {}", dto.getMobile(), e);
    throw new BusinessException(ExceptionCodeEnum.SERVER_ERROR, "邮件发送失败", e);
}

// ❌ 避免 - 吞掉异常
try {
    sendEmail(dto);
} catch (Exception e) {
    // 静默忽略
}

14.6 注释与文档

为生成的代码添加适当注释：

/**
 * 分页查询贷款报价线索列表
 *
 * <p>支持按手机号、状态、时间范围等条件过滤</p>
 *
 * @param req 查询请求参数，包含分页信息和过滤条件
 * @return 分页结果，包含符合条件的线索列表
 * @throws BusinessException 当查询参数无效时抛出
 */
@Override
public IPage<LoanQuoteLeadVO> getLoanQuoteLeadList(LoanQuoteLeadListReq req) {
    // 实现逻辑
}

TODO 注释使用：

标记需要后续检查或优化的代码
说明 TODO 的具体原因和期望的改进方向

// TODO: 考虑使用缓存优化频繁查询的性能
// TODO: 当前的同步邮件发送可能影响响应时间，后续改为异步
public SaveOrUpdateLoanQuoteLeadVO saveOrUpdate(SaveOrUpdateLoanQuoteLeadDTO dto) {
    // 实现
}

注释应解释"为什么"而非"是什么"：

// ✅ 推荐 - 解释原因
// 使用索引查询而非模糊搜索，因为 mobile 字段建立了索引
List<LoanQuoteLead> leads = baseMapper.selectList(
    new QueryWrapper<LoanQuoteLead>().eq("mobile", mobile)
);

// ❌ 避免 - 重复代码逻辑
// 查询 mobile 等于传入参数的记录
List<LoanQuoteLead> leads = baseMapper.selectList(
    new QueryWrapper<LoanQuoteLead>().eq("mobile", mobile)
);

Last Updated: 2026-01-26 | Version: 3.1

Name	fintorq-code-style
Description	Official code style and development standards for the Fintorq project. MUST be followed for all Java code generation.

fintorq-code-style

SKILL.md

name: fintorq-code-style description: Official code style and development standards for the Fintorq project. MUST be followed for all Java code generation. user-invocable: true

Fintorq Code Style & Standards

1. Tech Stack & Environment

2. Project Structure & Package Organization

Module Organization

Module Name Conventions

3. Naming Conventions

Class Naming

Method/Variable Naming

4. Architectural Layers & Class Types

4.1 Controller Layer

4.2 Service Layer

4.3 Mapper Layer

4.4 Entity/PO Layer

4.5 Data Transfer Objects (Req/DTO/VO/Resp)

4.6 【强制】分层架构数据类型约束

4.6.1 Controller 层约束

4.6.2 Service 层约束

4.6.3 Mapper 层约束

4.6.4 数据流向图

5. Dependency Injection & Configuration

5.1 依赖注入方式

5.2 配置类规范

6. API Design Standards

6.1 REST API 路径设计

6.2 输入验证与安全

6.3 权限控制

6.4 Swagger 文档注解

7. Data Access Standards

7.1 MyBatis-Plus 使用规范

7.2 枚举规范

7.3 数据权限

8. Exception Handling & Response Format

8.1 异常码体系

8.2 异常抛出

8.3 统一响应格式

9. Coding Standards

9.1 空值处理

9.2 线程安全

9.3 异常安全与资源管理

9.4 注释规范

9.5 健壮原则

9.6 注释规范

9.7 日志规范

9.8 工具类使用

11. Testing Standards

11.1 测试类命名

11.2 测试注解

11.3 Mock 规范

11.4 测试方法命名

11.5 断言规范

12. Common Patterns

12.1 分页查询模式

12.2 保存/更新模式

12.3 异步操作模式

13. Important Notes

13.1 禁止事项

13.2 时区处理

13.3 敏感数据过滤

14. AI 代码生成指引

14.1 可读性与清晰性

14.2 单一职责原则

14.3 避免重复与简单优先

14.4 可维护性和扩展性

14.5 错误处理与日志

14.6 注释与文档