跳到主要内容

代码规范与最佳实践

引用文件

本文引用的文件

目录​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言​

本规范文档面向 yudao-cloud 项目的开发团队，系统化梳理 Java 编码规范、模块化开发规范、Spring Boot 项目结构规范、异常与日志处理规范、代码审查清单与质量检查标准，并结合仓库中的真实实现给出落地建议与示例路径，帮助团队统一风格、提升可维护性与协作效率。

项目结构​

yudao-cloud 采用多模块聚合工程，顶层 POM 管理版本与插件，各功能域以 yudao-module-* 与 yudao-framework-* 模块形式组织，形成“网关 + 基础能力 + 业务模块”的分层架构。

Mermaid Diagram Code:

graph TB
Root["yudao-cloud 根 POM"]
Gateway["yudao-gateway 网关"]
Framework["yudao-framework 框架能力"]
Modules["yudao-module-* 业务模块"]
Root --> Gateway
Root --> Framework
Root --> Modules

图表来源

章节来源

核心组件​

  • 全局异常处理：统一将异常翻译为通用返回，并记录错误日志，便于定位问题。
  • 日志与审计：操作日志与 API 访问日志模型清晰，字段覆盖请求上下文与执行结果。
  • 代码生成：基于 Velocity 模板的代码生成器，统一生成 Controller/Service/Mapper/VO 等文件。
  • 规则引擎：基于 LiteFlow 的动态规则链，支持缓存、分布式锁与审批绑定。
  • 任务与 OTA：设备升级包元数据模型，体现审批与业务数据的结合。

章节来源

架构总览​

系统采用微服务架构，网关统一入口，后端服务按业务域拆分，基础设施模块提供运维与研发工具，核心业务模块围绕系统管理、设备管理、运营、黑名单、任务与 OTA、规则引擎展开。

Mermaid Diagram Code:

graph TB
subgraph "前端"
Admin["管理端"]
App["应用端"]
end
subgraph "网关层"
Gateway["yudao-gateway"]
end
subgraph "业务服务"
System["yudao-module-system"]
Infra["yudao-module-infra"]
Device["yudao-module-device"]
Launcher["yudao-module-launcher"]
Blacklist["yudao-module-blacklist"]
Task["yudao-module-task"]
Rule["yudao-module-rule"]
end
subgraph "中间件"
Nacos["Nacos"]
Redis["Redis"]
MySQL["MySQL"]
TDengine["TDengine"]
Kafka["Kafka"]
end
Admin --> Gateway
App --> Gateway
Gateway --> System
Gateway --> Infra
Gateway --> Device
Gateway --> Launcher
Gateway --> Blacklist
Gateway --> Task
Gateway --> Rule
System -.-> Nacos
Device -.-> TDengine
Task -.-> TDengine
Blacklist -.-> Kafka
Gateway -.-> Redis

图表来源

章节来源

详细组件分析​

Java 编码规范​

  • 命名约定
    • 类名：帕斯卡命名法（如 RuleLiteflowChainDO）
    • 方法名：驼峰命名法（如 buildExceptionLog）
    • 常量：大写下划线（如 REQUEST_PARAMS_MAX_LENGTH）
  • 缩进与格式
    • 使用 Maven 编译插件统一参数，保证参数名可见与一致性
  • 注释标准
    • 类注释：说明职责与用途（如 GlobalExceptionHandler 的“全局异常处理器”）
    • 方法注释：说明输入、输出、异常与边界条件（如 serviceExceptionHandler 的业务异常处理）
    • 字段注释：说明业务含义与约束（如 ApiAccessLogDO 的字段注释）

章节来源

模块化开发规范​

  • 包结构划分
    • infra 模块：以 /infra/ 开头的 Controller URL，以 infra_ 开头的表名，避免与其他模块冲突
  • 接口设计原则
    • 明确 Admin 与 App 两类接口的包划分，分别对应管理端与应用端
  • 异常处理规范
    • 全局异常处理器统一翻译 ServiceException 与常见参数校验异常，记录错误日志
  • 日志使用规范
    • 操作日志与 API 访问日志模型清晰，字段覆盖 traceId、用户信息、请求上下文、执行耗时与结果码

章节来源

Spring Boot 项目结构规范​

  • Controller、Service、Mapper、VO、DTO 职责与命名
    • Controller：统一生成路径与前缀，遵循模块与业务域划分
    • Service：业务实现，配合 Mapper 与 DO
    • Mapper：MyBatis Plus 映射，统一命名
    • VO/DTO：RespVO、ReqVO、SaveReqVO 等，模板生成
  • 代码生成器
    • 基于 Velocity 模板，生成后端 Java 代码与前端页面骨架
    • 生成路径与包名遵循约定，便于统一维护

Mermaid Diagram Code:

flowchart TD
Start["开始：选择表与模板"] --> Build["CodegenBuilder 解析表结构<br/>生成模块/业务名/类名"]
Build --> Engine["CodegenEngine 选择模板<br/>生成文件路径"]
Engine --> Render["渲染模板<br/>输出 Java/VO/Controller 等文件"]
Render --> End["结束：生成完成"]

图表来源

章节来源

规则引擎（LiteFlow）组件与流程​

  • 核心实体与缓存
    • RuleLiteflowChainDO：规则链实体，包含 EL 表达式与生效状态
    • RuleLiteflowChainCacheDTO：Redis 缓存传输对象
  • 规则获取与缓存机制
    • 多级缓存 + 分布式锁 + 数据库兜底，防止穿透与击穿
  • 业务绑定与审批
    • RuleBusinessApiServiceImpl：绑定/解绑规则，构建变更详情

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Service as "RuleBusinessApiServiceImpl"
participant Util as "RuleRunUtil"
participant Redis as "Redis"
participant DB as "数据库"
Client->>Service : "绑定/解绑请求"
Service->>Util : "获取规则详情"
Util->>Redis : "查询缓存"
alt 命中
Redis-->>Util : "返回规则DTO"
else 未命中
Util->>Util : "获取分布式锁"
Util->>Redis : "二次查询缓存"
alt 仍未命中
Util->>DB : "查询数据库"
DB-->>Util : "返回规则数据"
Util->>Redis : "写入缓存"
end
end
Util-->>Service : "返回规则DTO"
Service-->>Client : "返回结果"

图表来源

章节来源

任务与 OTA 数据模型​

  • UotaDetailDO：升级包元数据，包含文件关联、版本信息、有效性与草稿数据
  • 与 BPM 审批流程结合，体现“审批通过后生效”的业务闭环

Mermaid Diagram Code:

classDiagram
class UotaDetailDO {
+Long id
+String name
+Long infraFileId
+Integer company
+String packageName
+Integer versionCode
+String versionName
+String developer
+String describeInfo
+Boolean isAutoStart
+Boolean isSystemApp
+String installPath
+Boolean valid
+String draft
}

图表来源

章节来源

日志与异常处理​

  • 全局异常处理
    • 统一处理参数缺失、类型不匹配、校验失败、资源不存在、方法不允许、权限不足、业务异常与兜底异常
    • 对“表不存在”异常进行模块化提示，引导导入对应表结构
  • 日志常量
    • 定义敏感头过滤集合，避免日志泄露
  • 操作日志与 API 访问日志
    • 字段覆盖 traceId、用户信息、请求上下文、执行耗时与结果码，便于链路追踪与问题定位

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Handler as "GlobalExceptionHandler"
participant Logger as "错误日志记录"
Client->>Handler : "请求触发异常"
Handler->>Handler : "识别异常类型"
alt 表不存在
Handler->>Logger : "记录模块提示日志"
Handler-->>Client : "返回 NOT_IMPLEMENTED"
else 业务异常
Handler-->>Client : "返回 ServiceException 错误码与消息"
else 兜底异常
Handler->>Logger : "记录异常堆栈与上下文"
Handler-->>Client : "返回 INTERNAL_SERVER_ERROR"
end

图表来源

章节来源

驼峰与下划线转换工具​

  • AdaptiveFieldMatcher：提供 toCamelCase 与 toUnderlineCase 的转换逻辑，便于字段映射与序列化兼容

章节来源

依赖分析​

  • 顶层 POM 管理版本与插件，统一 Java 版本、Spring Boot 版本、Lombok、MapStruct、Surefire 与 Compiler 插件
  • 模块间通过 yudao-dependencies 进行依赖版本收敛
  • 各模块按需引入 yudao-framework-* 能力，如 web、security、mybatis、excel、mq、monitor 等

Mermaid Diagram Code:

graph TB
Root["根 POM"]
Deps["yudao-dependencies"]
Framework["yudao-framework/*"]
Modules["yudao-module-*"]
Root --> Deps
Root --> Framework
Root --> Modules

图表来源

章节来源

性能考虑​

  • 规则引擎缓存策略：Redis 缓存 + 分布式锁 + 数据库兜底，降低热点规则的数据库压力
  • 日志异步化：异常日志异步写入，避免阻塞主流程
  • 代码生成：模板化生成减少重复劳动，统一风格降低维护成本

章节来源

故障排查指南​

  • 表结构未导入
    • 现象：访问模块接口返回 NOT_IMPLEMENTED，提示参考对应模块文档开启
    • 处理：导入对应模块的表结构或启用模块
  • 参数校验失败
    • 现象：返回 BAD_REQUEST，包含具体字段校验失败信息
    • 处理：根据返回消息修正请求参数
  • 权限不足
    • 现象：返回 FORBIDDEN
    • 处理：确认登录态与权限配置
  • 未知异常
    • 现象：返回 INTERNAL_SERVER_ERROR 并记录异常日志
    • 处理：查看错误日志与链路追踪编号定位问题

章节来源

结论​

本规范文档基于 yudao-cloud 仓库的真实实现，总结了 Java 编码、模块化、Spring Boot 结构、异常与日志处理、规则引擎与 OTA 数据模型等方面的最佳实践与落地建议。建议团队在日常开发中严格遵循命名、注释、结构与流程规范，配合代码生成与统一异常处理，持续提升代码质量与交付效率。

附录​

代码审查清单与质量检查标准​

  • 命名与注释
    • 类/方法/常量命名是否符合约定
    • 类/方法/字段是否有清晰注释
  • 结构与职责
    • Controller/Service/Mapper/VO/DTO 是否按规范命名与放置
    • 是否遵循单一职责与高内聚低耦合
  • 异常与日志
    • 是否使用全局异常处理器统一处理
    • 是否记录必要的日志字段（traceId、用户信息、请求上下文）
  • 性能与安全
    • 是否使用缓存与分布式锁优化热点数据
    • 是否过滤敏感头（Authorization）避免日志泄露
  • 代码生成与一致性
    • 是否使用代码生成器生成统一风格的代码
    • 是否遵循模板约定与包结构

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答