# RuoYi-Cloud 微服务架构开发规范 > 本文档定义了 RuoYi-Cloud 微服务项目的标准架构、编码规范和最佳实践。 > > **版本**: v1.0 > **更新日期**: 2026-01-17 --- ## 目录 - [一、项目结构规范](#一项目结构规范) - [二、Maven配置规范](#二maven配置规范) - [三、配置文件规范](#三配置文件规范) - [四、数据库层规范](#四数据库层规范) - [五、领域层规范](#五领域层domain规范) - [六、服务层规范](#六服务层service规范) - [七、控制器层规范](#七控制器层controller规范) - [八、API层规范](#八api层规范) - [九、依赖注入规范](#九依赖注入规范) - [十、命名规范](#十命名规范) --- ## 一、项目结构规范 ### 1.1 模块目录结构 ``` ruoyi-modules/{module-name}/ ├── src/main/java/com/ruoyi/{module}/ │ ├── controller/ # 控制器层 │ │ ├── {Entity}Controller.java │ │ └── convert/ # Controller层对象转换 │ ├── service/ # 服务层 │ │ ├── api/ # 服务接口 │ │ │ └── I{Entity}Service.java │ │ ├── impl/ # 服务实现 │ │ │ └── {Entity}ServiceImpl.java │ │ ├── dto/ # 数据传输对象 │ │ │ └── {Entity}DTO.java │ │ └── convert/ # Service层对象转换 │ │ └── {Entity}ServiceConvert.java │ ├── domain/ # 领域层 │ │ ├── api/ # 领域接口 │ │ │ └── I{Entity}Domain.java │ │ ├── impl/ # 领域实现 │ │ │ └── {Entity}DomainImpl.java │ │ ├── model/ # 领域模型 │ │ │ └── {Entity}.java │ │ └── convert/ # Domain层对象转换 │ │ └── {Entity}DomainConvert.java │ └── mapper/ # 数据访问层 │ ├── entity/ # 数据库实体 │ │ └── {Entity}Entity.java │ └── {Entity}Mapper.java # MyBatis Mapper接口 ├── src/main/resources/ │ ├── bootstrap.yml # 启动配置 │ └── mapper/{module}/ # MyBatis XML映射文件 │ └── {Entity}Mapper.xml └── pom.xml # Maven配置 ruoyi-api/{module-name}-api-{submodule}/ ├── src/main/java/com/ruoyi/{module}/api/ │ ├── domain/ # VO对象 │ │ └── {Entity}VO.java │ ├── factory/ # Feign降级工厂 │ │ └── Remote{Module}FallbackFactory.java │ └── Remote{Module}Service.java # Feign客户端接口 └── pom.xml ``` ### 1.2 分层架构说明 ``` Controller Layer (控制器层) ↓ VO → DTO Service Layer (服务层) ↓ DTO → Model Domain Layer (领域层) ↓ Model → Entity Mapper Layer (数据访问层) ↓ Database (数据库) ``` **各层职责：** - **Controller层**: 处理HTTP请求，参数验证，调用Service层，返回响应 - **Service层**: 业务逻辑编排，事务管理，调用Domain层 - **Domain层**: 领域业务逻辑，封装Mapper操作，对象转换 - **Mapper层**: 数据库访问，SQL执行 ### 1.3 端口分配规范 | 端口范围 | 用途 | 示例 | |---------|------|------| | 9200-9209 | 基础服务 | ruoyi-auth(9200), ruoyi-modules-system(9201), ruoyi-modules-gen(9202), ruoyi-modules-job(9203) | | 9210-9299 | 业务服务 | tuoheng-device(9210), tuoheng-airline(9211), tuoheng-approval(9212), tuoheng-fms(9213), tuoheng-media(9214), tuoheng-task(9215) | | 9100 | 监控服务 | ruoyi-visual-monitor(9100) | | 9300+ | 特殊服务 | ruoyi-modules-file(9300) | **端口分配原则：** - 新增业务服务从 9216 开始递增 - 避免端口冲突 - Docker 端口映射必须与 bootstrap.yml 配置一致 --- ## 二、Maven配置规范 ### 2.1 根 pom.xml 配置 #### 2.1.1 添加服务名称常量 在 `ruoyi-common-core/src/main/java/com/ruoyi/common/core/constant/ServiceNameConstants.java` 中添加： ```java /** * {模块中文名}服务的serviceid */ public static final String {MODULE}_SERVICE = "{module-name}"; ``` **示例：** ```java /** * 设备服务的serviceid */ public static final String DEVICE_SERVICE = "tuoheng-device"; /** * 航线服务的serviceid */ public static final String AIRLINE_SERVICE = "tuoheng-airline"; ``` #### 2.1.2 添加依赖管理 在根 `pom.xml` 的 `` 中添加： ```xml com.ruoyi {module-name}-api-{submodule} ${ruoyi.version} ``` **示例：** ```xml com.ruoyi tuoheng-api-device ${ruoyi.version} ``` ### 2.2 ruoyi-api/pom.xml 配置 在 `ruoyi-api/pom.xml` 的 `` 中添加： ```xml {module-name}-api-{submodule} ``` **示例：** ```xml ruoyi-api-system tuoheng-api-device tuoheng-api-airline ``` ### 2.3 业务模块 pom.xml 标准配置 ```xml com.ruoyi ruoyi-modules 3.6.7 4.0.0 {module-name} {module-name}系统模块 com.ruoyi {module-name}-api-{submodule} com.alibaba.cloud spring-cloud-starter-alibaba-nacos-discovery com.alibaba.cloud spring-cloud-starter-alibaba-nacos-config com.alibaba.cloud spring-cloud-starter-alibaba-sentinel org.springframework.boot spring-boot-starter-actuator com.mysql mysql-connector-j com.ruoyi ruoyi-common-datasource com.ruoyi ruoyi-common-datascope com.ruoyi ruoyi-common-log com.ruoyi ruoyi-common-swagger org.flywaydb flyway-core org.flywaydb flyway-mysql ${project.artifactId} org.springframework.boot spring-boot-maven-plugin repackage ``` ### 2.4 API 模块 pom.xml 标准配置 ```xml com.ruoyi ruoyi-api 3.6.7 4.0.0 {module-name}-api-{submodule} {module-name} API模块 com.ruoyi ruoyi-common-core org.springframework.cloud spring-cloud-starter-openfeign ``` --- ## 三、配置文件规范 ### 3.1 bootstrap.yml 标准配置 ```yaml # Tomcat server: port: {port} # 按照端口分配规范设置，例如: 9210 # Spring spring: application: # 应用名称 name: {module-name} profiles: # 环境配置 active: prod flyway: table: flyway_{module}_schema_history # 自定义历史表名 baseline-on-migrate: true # 在nacos中也有配置 baseline-version: 0 # 在nacos中也有配置 cloud: nacos: discovery: # 服务注册地址 server-addr: ruoyi-nacos:8848 config: # 配置中心地址 server-addr: ruoyi-nacos:8848 # 配置文件格式 file-extension: yml # 共享配置 shared-configs: - application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension} ``` **配置说明：** - `server.port`: 必须按照端口分配规范设置 - `spring.application.name`: 服务名称，用于服务注册和发现 - `flyway.table`: Flyway 历史表名，格式为 `flyway_{module}_schema_history` ### 3.2 Docker Compose 配置 在 `docker/docker-compose.yml` 中添加服务配置： ```yaml {module-name}-modules-{submodule}: container_name: {module-name}-modules-{submodule} image: {module-name}-modules-{submodule}-runtime build: context: ./ruoyi/modules/{submodule} dockerfile: dockerfile environment: - TZ=Asia/Shanghai ports: - "{port}:{port}" # 宿主机端口:容器端口，必须与bootstrap.yml一致 depends_on: - ruoyi-redis - ruoyi-mysql links: - ruoyi-redis - ruoyi-mysql ``` **重要提示：** - Docker 端口映射格式：`宿主机端口:容器端口` - 容器端口必须与 `bootstrap.yml` 中的 `server.port` 一致 - 宿主机端口不能重复，但容器端口可以相同（因为在不同容器中） --- ## 四、数据库层规范 ### 4.1 Flyway 迁移脚本命名规范 **目录结构：** ``` src/main/resources/db/migration/ ├── V1__Create_{module}_initial_tables.sql ├── V2__Add_{feature}_tables.sql ├── V3__Modify_{table}_add_{field}.sql ├── V4__Add_{table}_indexes.sql └── V5__Update_{table}_data.sql ``` **命名规则：** - 格式：`V{版本号}__{描述}.sql` - 版本号：从1开始递增，不能跳号 - 描述：使用下划线分隔的英文描述，首字母大写 - 操作类型前缀： - `Create`: 创建表或数据库对象 - `Add`: 添加字段、索引或数据 - `Modify`: 修改表结构或字段 - `Drop`: 删除表或字段 - `Update`: 更新数据 **示例：** ``` V1__Create_device_tables.sql V2__Add_device_gateway_field.sql V3__Add_foreign_key_indexes.sql V4__Modify_device_add_status_field.sql ``` ### 4.2 数据库表设计规范 ```sql CREATE TABLE IF NOT EXISTS {module}_{table_name} ( {table}_id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', {field_name} VARCHAR(100) COMMENT '字段说明', -- 继承自BaseEntity的字段 create_by VARCHAR(64) DEFAULT '' COMMENT '创建者', create_time DATETIME COMMENT '创建时间', update_by VARCHAR(64) DEFAULT '' COMMENT '更新者', update_time DATETIME COMMENT '更新时间', remark VARCHAR(500) DEFAULT NULL COMMENT '备注', PRIMARY KEY ({table}_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='{表中文说明}'; ``` **设计原则：** 1. **表名格式**: `{module}_{table_name}`，全小写，下划线分隔 - 示例：`device_device`, `device_dock`, `airline_route` 2. **主键命名**: `{table}_id`，类型为 `BIGINT`，`AUTO_INCREMENT` - 示例：`device_id`, `dock_id`, `route_id` 3. **BaseEntity 字段**: 所有表必须包含以下5个字段 ```sql create_by VARCHAR(64) DEFAULT '' COMMENT '创建者', create_time DATETIME COMMENT '创建时间', update_by VARCHAR(64) DEFAULT '' COMMENT '更新者', update_time DATETIME COMMENT '更新时间', remark VARCHAR(500) DEFAULT NULL COMMENT '备注' ``` 4. **字符集**: 统一使用 `utf8mb4` 5. **存储引擎**: 统一使用 `InnoDB` 6. **注释**: 必须添加表注释和字段注释 7. **外键**: 不使用数据库外键约束，通过应用层维护关联关系 ### 4.3 索引设计规范 ```sql -- 外键索引 CREATE INDEX idx_{table}_{foreign_key} ON {module}_{table}({foreign_key}); -- 复合索引 CREATE INDEX idx_{table}_{field1}_{field2} ON {module}_{table}({field1}, {field2}); -- 唯一索引 CREATE UNIQUE INDEX uk_{table}_{field} ON {module}_{table}({field}); ``` **索引命名规则：** - 普通索引：`idx_{table}_{field}` - 唯一索引：`uk_{table}_{field}` - 复合索引：`idx_{table}_{field1}_{field2}` **索引设计原则：** - 所有外键字段必须添加索引 - 频繁查询的字段添加索引 - 复合索引遵循最左前缀原则 - 避免过多索引影响写入性能 **示例：** ```sql -- 外键索引 CREATE INDEX idx_dock_device_id ON device_dock(device_id); CREATE INDEX idx_aircraft_device_id ON device_aircraft(device_id); -- 复合索引 CREATE INDEX idx_dock_device_status ON device_dock(device_id, status); -- 唯一索引 CREATE UNIQUE INDEX uk_device_sn ON device_device(device_sn); ``` ### 4.4 Entity 实体类规范 **位置**: `src/main/java/com/ruoyi/{module}/mapper/entity/{Entity}Entity.java` ```java package com.ruoyi.{module}.mapper.entity; import com.ruoyi.common.core.web.domain.BaseEntity; /** * {表中文说明}实体对象 {module}_{table} * Mapper 层实体，对应数据库表 * * @author ruoyi * @date {date} */ public class {Entity}Entity extends BaseEntity { private static final long serialVersionUID = 1L; /** 主键ID */ private Long {entity}Id; /** 字段说明 */ private String fieldName; public Long get{Entity}Id() { return {entity}Id; } public void set{Entity}Id(Long {entity}Id) { this.{entity}Id = {entity}Id; } public String getFieldName() { return fieldName; } public void setFieldName(String fieldName) { this.fieldName = fieldName; } @Override public String toString() { return "{Entity}Entity{" + "{entity}Id=" + {entity}Id + ", fieldName='" + fieldName + '\'' + '}'; } } ``` **规范要点：** - 必须继承 `BaseEntity` - 类名格式：`{Entity}Entity` - 必须实现 `serialVersionUID` - 使用标准的 Getter/Setter 方法 - 重写 `toString()` 方法 ### 4.5 Mapper 接口规范 **位置**: `src/main/java/com/ruoyi/{module}/mapper/{Entity}Mapper.java` ```java package com.ruoyi.{module}.mapper; import com.ruoyi.{module}.mapper.entity.{Entity}Entity; import java.util.List; /** * {表中文说明}Mapper接口 * * @author ruoyi * @date {date} */ public interface {Entity}Mapper { /** * 查询{表中文说明}列表 * * @param {entity}Entity {表中文说明} * @return {表中文说明}集合 */ List<{Entity}Entity> select{Entity}List({Entity}Entity {entity}Entity); /** * 根据ID查询{表中文说明} * * @param {entity}Id 主键ID * @return {表中文说明} */ {Entity}Entity select{Entity}ById(Long {entity}Id); /** * 新增{表中文说明} * * @param {entity}Entity {表中文说明} * @return 结果 */ int insert{Entity}({Entity}Entity {entity}Entity); /** * 修改{表中文说明} * * @param {entity}Entity {表中文说明} * @return 结果 */ int update{Entity}({Entity}Entity {entity}Entity); /** * 删除{表中文说明} * * @param {entity}Id 主键ID * @return 结果 */ int delete{Entity}ById(Long {entity}Id); /** * 批量删除{表中文说明} * * @param {entity}Ids 主键ID数组 * @return 结果 */ int delete{Entity}ByIds(Long[] {entity}Ids); } ``` **方法命名规范：** - 查询列表：`select{Entity}List` - 查询单个：`select{Entity}ById` - 新增：`insert{Entity}` - 修改：`update{Entity}` - 删除：`delete{Entity}ById` - 批量删除：`delete{Entity}ByIds` ### 4.6 Mapper XML 规范 **位置**: `src/main/resources/mapper/{module}/{Entity}Mapper.xml` ```xml select {entity}_id, field_name, create_by, create_time, update_by, update_time, remark from {module}_{table} insert into {module}_{table} field_name, create_by, remark, create_time #{fieldName}, #{createBy}, #{remark}, sysdate() update {module}_{table} field_name = #{fieldName}, update_by = #{updateBy}, remark = #{remark}, update_time = sysdate() where {entity}_id = #{{{entity}Id}} delete from {module}_{table} where {entity}_id = #{{{entity}Id}} delete from {module}_{table} where {entity}_id in #{{{entity}Id}} ``` **规范要点：** - 使用 `` 定义结果映射 - 使用 `` 定义可复用的 SQL 片段 - 使用动态 SQL 标签：``, ``, `` - 插入操作使用 `useGeneratedKeys="true"` 返回主键 - 时间字段使用 `sysdate()` 函数 --- ## 五、领域层（Domain）规范 ### 5.1 Model 领域模型规范 **位置**: `src/main/java/com/ruoyi/{module}/domain/model/{Entity}.java` ```java package com.ruoyi.{module}.domain.model; import com.ruoyi.common.core.web.domain.BaseEntity; /** * {表中文说明}领域模型 * Domain 层模型，用于业务逻辑处理 * * @author ruoyi * @date {date} */ public class {Entity} extends BaseEntity { private static final long serialVersionUID = 1L; /** 主键ID */ private Long {entity}Id; /** 字段说明 */ private String fieldName; public Long get{Entity}Id() { return {entity}Id; } public void set{Entity}Id(Long {entity}Id) { this.{entity}Id = {entity}Id; } public String getFieldName() { return fieldName; } public void setFieldName(String fieldName) { this.fieldName = fieldName; } @Override public String toString() { return "{Entity}{" + "{entity}Id=" + {entity}Id + ", fieldName='" + fieldName + '\'' + '}'; } } ``` **规范要点：** - 类名不带后缀，直接使用实体名 - 必须继承 `BaseEntity` - 字段和方法与 Entity 保持一致 ### 5.2 Domain API 接口规范 **位置**: `src/main/java/com/ruoyi/{module}/domain/api/I{Entity}Domain.java` ```java package com.ruoyi.{module}.domain.api; import com.ruoyi.{module}.domain.model.{Entity}; import java.util.List; /** * {表中文说明}领域接口 * * @author ruoyi * @date {date} */ public interface I{Entity}Domain { /** * 查询{表中文说明}列表 */ List<{Entity}> select{Entity}List({Entity} {entity}); /** * 根据ID查询{表中文说明} */ {Entity} select{Entity}ById(Long {entity}Id); /** * 新增{表中文说明} */ int insert{Entity}({Entity} {entity}); /** * 修改{表中文说明} */ int update{Entity}({Entity} {entity}); /** * 删除{表中文说明} */ int delete{Entity}ById(Long {entity}Id); /** * 批量删除{表中文说明} */ int delete{Entity}ByIds(Long[] {entity}Ids); } ``` ### 5.3 Domain 实现类规范 **位置**: `src/main/java/com/ruoyi/{module}/domain/impl/{Entity}DomainImpl.java` ```java package com.ruoyi.{module}.domain.impl; import com.ruoyi.{module}.domain.api.I{Entity}Domain; import com.ruoyi.{module}.domain.convert.{Entity}DomainConvert; import com.ruoyi.{module}.domain.model.{Entity}; import com.ruoyi.{module}.mapper.{Entity}Mapper; import com.ruoyi.{module}.mapper.entity.{Entity}Entity; import org.springframework.stereotype.Component; import java.util.List; /** * {表中文说明}领域实现 * * @author ruoyi * @date {date} */ @Component public class {Entity}DomainImpl implements I{Entity}Domain { private final {Entity}Mapper {entity}Mapper; public {Entity}DomainImpl({Entity}Mapper {entity}Mapper) { this.{entity}Mapper = {entity}Mapper; } @Override public List<{Entity}> select{Entity}List({Entity} {entity}) { {Entity}Entity entity = {Entity}DomainConvert.toEntity({entity}); List<{Entity}Entity> entityList = {entity}Mapper.select{Entity}List(entity); return {Entity}DomainConvert.toModelList(entityList); } @Override public {Entity} select{Entity}ById(Long {entity}Id) { {Entity}Entity entity = {entity}Mapper.select{Entity}ById({entity}Id); return {Entity}DomainConvert.toModel(entity); } @Override public int insert{Entity}({Entity} {entity}) { {Entity}Entity entity = {Entity}DomainConvert.toEntity({entity}); return {entity}Mapper.insert{Entity}(entity); } @Override public int update{Entity}({Entity} {entity}) { {Entity}Entity entity = {Entity}DomainConvert.toEntity({entity}); return {entity}Mapper.update{Entity}(entity); } @Override public int delete{Entity}ById(Long {entity}Id) { return {entity}Mapper.delete{Entity}ById({entity}Id); } @Override public int delete{Entity}ByIds(Long[] {entity}Ids) { return {entity}Mapper.delete{Entity}ByIds({entity}Ids); } } ``` **重要规范：** - 使用 `@Component` 注解 - 使用**构造器注入**（Constructor Injection） - 字段声明为 `private final` - 通过 Convert 类进行对象转换 ### 5.4 Domain Convert 转换类规范 **位置**: `src/main/java/com/ruoyi/{module}/domain/convert/{Entity}DomainConvert.java` ```java package com.ruoyi.{module}.domain.convert; import com.ruoyi.{module}.domain.model.{Entity}; import com.ruoyi.{module}.mapper.entity.{Entity}Entity; import org.springframework.beans.BeanUtils; import java.util.ArrayList; import java.util.List; /** * {表中文说明}领域转换类 * * @author ruoyi * @date {date} */ public class {Entity}DomainConvert { /** * Model 转 Entity */ public static {Entity}Entity toEntity({Entity} model) { if (model == null) { return null; } {Entity}Entity entity = new {Entity}Entity(); BeanUtils.copyProperties(model, entity); return entity; } /** * Entity 转 Model */ public static {Entity} toModel({Entity}Entity entity) { if (entity == null) { return null; } {Entity} model = new {Entity}(); BeanUtils.copyProperties(entity, model); return model; } /** * Entity List 转 Model List */ public static List<{Entity}> toModelList(List<{Entity}Entity> entityList) { if (entityList == null || entityList.isEmpty()) { return new ArrayList<>(); } List<{Entity}> modelList = new ArrayList<>(); for ({Entity}Entity entity : entityList) { modelList.add(toModel(entity)); } return modelList; } /** * Model List 转 Entity List */ public static List<{Entity}Entity> toEntityList(List<{Entity}> modelList) { if (modelList == null || modelList.isEmpty()) { return new ArrayList<>(); } List<{Entity}Entity> entityList = new ArrayList<>(); for ({Entity} model : modelList) { entityList.add(toEntity(model)); } return entityList; } } ``` **规范要点：** - 工具类，所有方法为 `public static` - 使用 `BeanUtils.copyProperties` 进行属性拷贝 - 提供空值检查 - 提供单个对象和列表转换方法 --- ## 六、服务层（Service）规范 ### 6.1 DTO 数据传输对象规范 **位置**: `src/main/java/com/ruoyi/{module}/service/dto/{Entity}DTO.java` ```java package com.ruoyi.{module}.service.dto; import com.ruoyi.common.core.web.domain.BaseEntity; /** * {表中文说明}数据传输对象 * Service 层 DTO，用于业务逻辑编排 * * @author ruoyi * @date {date} */ public class {Entity}DTO extends BaseEntity { private static final long serialVersionUID = 1L; /** 主键ID */ private Long {entity}Id; /** 字段说明 */ private String fieldName; public Long get{Entity}Id() { return {entity}Id; } public void set{Entity}Id(Long {entity}Id) { this.{entity}Id = {entity}Id; } public String getFieldName() { return fieldName; } public void setFieldName(String fieldName) { this.fieldName = fieldName; } @Override public String toString() { return "{Entity}DTO{" + "{entity}Id=" + {entity}Id + ", fieldName='" + fieldName + '\'' + '}'; } } ``` **规范要点：** - 类名格式：`{Entity}DTO` - 必须继承 `BaseEntity` - 字段和方法与 Model 保持一致 ### 6.2 Service API 接口规范 **位置**: `src/main/java/com/ruoyi/{module}/service/api/I{Entity}Service.java` ```java package com.ruoyi.{module}.service.api; import com.ruoyi.{module}.service.dto.{Entity}DTO; import java.util.List; /** * {表中文说明}服务接口 * * @author ruoyi * @date {date} */ public interface I{Entity}Service { /** * 查询{表中文说明}列表 */ List<{Entity}DTO> select{Entity}List({Entity}DTO {entity}DTO); /** * 根据ID查询{表中文说明} */ {Entity}DTO select{Entity}ById(Long {entity}Id); /** * 新增{表中文说明} */ int insert{Entity}({Entity}DTO {entity}DTO); /** * 修改{表中文说明} */ int update{Entity}({Entity}DTO {entity}DTO); /** * 删除{表中文说明} */ int delete{Entity}ById(Long {entity}Id); /** * 批量删除{表中文说明} */ int delete{Entity}ByIds(Long[] {entity}Ids); } ``` ### 6.3 Service 实现类规范 **位置**: `src/main/java/com/ruoyi/{module}/service/impl/{Entity}ServiceImpl.java` ```java package com.ruoyi.{module}.service.impl; import com.ruoyi.{module}.domain.api.I{Entity}Domain; import com.ruoyi.{module}.domain.model.{Entity}; import com.ruoyi.{module}.service.api.I{Entity}Service; import com.ruoyi.{module}.service.convert.{Entity}ServiceConvert; import com.ruoyi.{module}.service.dto.{Entity}DTO; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.List; /** * {表中文说明}服务实现 * * @author ruoyi * @date {date} */ @Service public class {Entity}ServiceImpl implements I{Entity}Service { @Autowired private I{Entity}Domain {entity}Domain; @Override public List<{Entity}DTO> select{Entity}List({Entity}DTO {entity}DTO) { {Entity} model = {Entity}ServiceConvert.toModel({entity}DTO); List<{Entity}> modelList = {entity}Domain.select{Entity}List(model); return {Entity}ServiceConvert.toDTOList(modelList); } @Override public {Entity}DTO select{Entity}ById(Long {entity}Id) { {Entity} model = {entity}Domain.select{Entity}ById({entity}Id); return {Entity}ServiceConvert.toDTO(model); } @Override public int insert{Entity}({Entity}DTO {entity}DTO) { {Entity} model = {Entity}ServiceConvert.toModel({entity}DTO); return {entity}Domain.insert{Entity}(model); } @Override public int update{Entity}({Entity}DTO {entity}DTO) { {Entity} model = {Entity}ServiceConvert.toModel({entity}DTO); return {entity}Domain.update{Entity}(model); } @Override public int delete{Entity}ById(Long {entity}Id) { return {entity}Domain.delete{Entity}ById({entity}Id); } @Override public int delete{Entity}ByIds(Long[] {entity}Ids) { return {entity}Domain.delete{Entity}ByIds({entity}Ids); } } ``` **重要规范：** - 使用 `@Service` 注解 - 使用 `@Autowired` 字段注入（Service层使用字段注入） - 通过 Convert 类进行 DTO ↔ Model 转换 ### 6.4 Service Convert 转换类规范 **位置**: `src/main/java/com/ruoyi/{module}/service/convert/{Entity}ServiceConvert.java` ```java package com.ruoyi.{module}.service.convert; import com.ruoyi.{module}.domain.model.{Entity}; import com.ruoyi.{module}.service.dto.{Entity}DTO; import org.springframework.beans.BeanUtils; import java.util.ArrayList; import java.util.List; /** * {表中文说明}服务转换类 * * @author ruoyi * @date {date} */ public class {Entity}ServiceConvert { /** * DTO 转 Model */ public static {Entity} toModel({Entity}DTO dto) { if (dto == null) { return null; } {Entity} model = new {Entity}(); BeanUtils.copyProperties(dto, model); return model; } /** * Model 转 DTO */ public static {Entity}DTO toDTO({Entity} model) { if (model == null) { return null; } {Entity}DTO dto = new {Entity}DTO(); BeanUtils.copyProperties(model, dto); return dto; } /** * Model List 转 DTO List */ public static List<{Entity}DTO> toDTOList(List<{Entity}> modelList) { if (modelList == null || modelList.isEmpty()) { return new ArrayList<>(); } List<{Entity}DTO> dtoList = new ArrayList<>(); for ({Entity} model : modelList) { dtoList.add(toDTO(model)); } return dtoList; } /** * DTO List 转 Model List */ public static List<{Entity}> toModelList(List<{Entity}DTO> dtoList) { if (dtoList == null || dtoList.isEmpty()) { return new ArrayList<>(); } List<{Entity}> modelList = new ArrayList<>(); for ({Entity}DTO dto : dtoList) { modelList.add(toModel(dto)); } return modelList; } } ``` --- ## 七、控制器层（Controller）规范 ### 7.1 Controller 类规范 **位置**: `src/main/java/com/ruoyi/{module}/controller/{Entity}Controller.java` ```java package com.ruoyi.{module}.controller; import com.ruoyi.common.core.web.controller.BaseController; import com.ruoyi.common.core.web.domain.AjaxResult; import com.ruoyi.common.core.web.page.TableDataInfo; import com.ruoyi.common.log.annotation.Log; import com.ruoyi.common.log.enums.BusinessType; import com.ruoyi.common.security.annotation.RequiresPermissions; import com.ruoyi.{module}.controller.convert.{Entity}ControllerConvert; import com.ruoyi.{module}.service.api.I{Entity}Service; import com.ruoyi.{module}.service.dto.{Entity}DTO; import com.ruoyi.{module}.api.domain.{Entity}VO; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; /** * {表中文说明}控制器 * * @author ruoyi * @date {date} */ @RestController @RequestMapping("/{entity}") public class {Entity}Controller extends BaseController { @Autowired private I{Entity}Service {entity}Service; /** * 查询{表中文说明}列表 */ @RequiresPermissions("{module}:{entity}:list") @GetMapping("/list") public TableDataInfo list({Entity}VO {entity}VO) { startPage(); {Entity}DTO dto = {Entity}ControllerConvert.toDTO({entity}VO); List<{Entity}DTO> list = {entity}Service.select{Entity}List(dto); List<{Entity}VO> voList = {Entity}ControllerConvert.toVOList(list); return getDataTable(voList); } /** * 获取{表中文说明}详细信息 */ @RequiresPermissions("{module}:{entity}:query") @GetMapping(value = "/{id}") public AjaxResult getInfo(@PathVariable("id") Long {entity}Id) { {Entity}DTO dto = {entity}Service.select{Entity}ById({entity}Id); {Entity}VO vo = {Entity}ControllerConvert.toVO(dto); return success(vo); } /** * 新增{表中文说明} */ @RequiresPermissions("{module}:{entity}:add") @Log(title = "{表中文说明}", businessType = BusinessType.INSERT) @PostMapping public AjaxResult add(@RequestBody {Entity}VO {entity}VO) { {Entity}DTO dto = {Entity}ControllerConvert.toDTO({entity}VO); return toAjax({entity}Service.insert{Entity}(dto)); } /** * 修改{表中文说明} */ @RequiresPermissions("{module}:{entity}:edit") @Log(title = "{表中文说明}", businessType = BusinessType.UPDATE) @PutMapping public AjaxResult edit(@RequestBody {Entity}VO {entity}VO) { {Entity}DTO dto = {Entity}ControllerConvert.toDTO({entity}VO); return toAjax({entity}Service.update{Entity}(dto)); } /** * 删除{表中文说明} */ @RequiresPermissions("{module}:{entity}:remove") @Log(title = "{表中文说明}", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public AjaxResult remove(@PathVariable Long[] ids) { return toAjax({entity}Service.delete{Entity}ByIds(ids)); } } ``` **规范要点：** - 继承 `BaseController` - 使用 `@RestController` 和 `@RequestMapping` - 使用 `@Autowired` 字段注入 - 使用 `@RequiresPermissions` 进行权限控制 - 使用 `@Log` 记录操作日志 - 通过 Convert 类进行 VO ↔ DTO 转换 ### 7.2 Controller Convert 转换类规范 **位置**: `src/main/java/com/ruoyi/{module}/controller/convert/{Entity}ControllerConvert.java` ```java package com.ruoyi.{module}.controller.convert; import com.ruoyi.{module}.api.domain.{Entity}VO; import com.ruoyi.{module}.service.dto.{Entity}DTO; import org.springframework.beans.BeanUtils; import java.util.ArrayList; import java.util.List; /** * {表中文说明}控制器转换类 * * @author ruoyi * @date {date} */ public class {Entity}ControllerConvert { /** * VO 转 DTO */ public static {Entity}DTO toDTO({Entity}VO vo) { if (vo == null) { return null; } {Entity}DTO dto = new {Entity}DTO(); BeanUtils.copyProperties(vo, dto); return dto; } /** * DTO 转 VO */ public static {Entity}VO toVO({Entity}DTO dto) { if (dto == null) { return null; } {Entity}VO vo = new {Entity}VO(); BeanUtils.copyProperties(dto, vo); return vo; } /** * DTO List 转 VO List */ public static List<{Entity}VO> toVOList(List<{Entity}DTO> dtoList) { if (dtoList == null || dtoList.isEmpty()) { return new ArrayList<>(); } List<{Entity}VO> voList = new ArrayList<>(); for ({Entity}DTO dto : dtoList) { voList.add(toVO(dto)); } return voList; } /** * VO List 转 DTO List */ public static List<{Entity}DTO> toDTOList(List<{Entity}VO> voList) { if (voList == null || voList.isEmpty()) { return new ArrayList<>(); } List<{Entity}DTO> dtoList = new ArrayList<>(); for ({Entity}VO vo : voList) { dtoList.add(toDTO(vo)); } return dtoList; } } ``` --- ## 八、API层规范 ### 8.1 VO 视图对象规范 **位置**: `ruoyi-api/{module-name}-api-{submodule}/src/main/java/com/ruoyi/{module}/api/domain/{Entity}VO.java` ```java package com.ruoyi.{module}.api.domain; import com.ruoyi.common.core.web.domain.BaseEntity; /** * {表中文说明}视图对象 * API 层 VO，用于前后端数据交互 * * @author ruoyi * @date {date} */ public class {Entity}VO extends BaseEntity { private static final long serialVersionUID = 1L; /** 主键ID */ private Long {entity}Id; /** 字段说明 */ private String fieldName; public Long get{Entity}Id() { return {entity}Id; } public void set{Entity}Id(Long {entity}Id) { this.{entity}Id = {entity}Id; } public String getFieldName() { return fieldName; } public void setFieldName(String fieldName) { this.fieldName = fieldName; } @Override public String toString() { return "{Entity}VO{" + "{entity}Id=" + {entity}Id + ", fieldName='" + fieldName + '\'' + '}'; } } ``` ### 8.2 Remote Service 接口规范 **位置**: `ruoyi-api/{module-name}-api-{submodule}/src/main/java/com/ruoyi/{module}/api/Remote{Module}Service.java` ```java package com.ruoyi.{module}.api; import com.ruoyi.common.core.constant.SecurityConstants; import com.ruoyi.common.core.constant.ServiceNameConstants; import com.ruoyi.common.core.domain.R; import com.ruoyi.{module}.api.domain.{Entity}VO; import com.ruoyi.{module}.api.factory.Remote{Module}FallbackFactory; import org.springframework.cloud.openfeign.FeignClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestHeader; /** * {模块中文名}远程服务 * * @author ruoyi * @date {date} */ @FeignClient(contextId = "remote{Module}Service", value = ServiceNameConstants.{MODULE}_SERVICE, fallbackFactory = Remote{Module}FallbackFactory.class) public interface Remote{Module}Service { /** * 根据ID获取{表中文说明} */ @GetMapping("/{entity}/{id}") R<{Entity}VO> get{Entity}ById(@PathVariable("id") Long id, @RequestHeader(SecurityConstants.FROM_SOURCE) String source); } ``` **规范要点：** - 使用 `@FeignClient` 注解 - `contextId` 格式：`remote{Module}Service` - `value` 使用 `ServiceNameConstants` 中定义的常量 - 配置 `fallbackFactory` 降级工厂 - 方法参数必须包含 `@RequestHeader(SecurityConstants.FROM_SOURCE) String source` ### 8.3 Fallback Factory 降级工厂规范 **位置**: `ruoyi-api/{module-name}-api-{submodule}/src/main/java/com/ruoyi/{module}/api/factory/Remote{Module}FallbackFactory.java` ```java package com.ruoyi.{module}.api.factory; import com.ruoyi.common.core.domain.R; import com.ruoyi.{module}.api.Remote{Module}Service; import com.ruoyi.{module}.api.domain.{Entity}VO; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.cloud.openfeign.FallbackFactory; import org.springframework.stereotype.Component; /** * {模块中文名}服务降级处理 * * @author ruoyi * @date {date} */ @Component public class Remote{Module}FallbackFactory implements FallbackFactory { private static final Logger log = LoggerFactory.getLogger(Remote{Module}FallbackFactory.class); @Override public Remote{Module}Service create(Throwable throwable) { log.error("{模块中文名}服务调用失败:{}", throwable.getMessage()); return new Remote{Module}Service() { @Override public R<{Entity}VO> get{Entity}ById(Long id, String source) { return R.fail("获取{表中文说明}失败:" + throwable.getMessage()); } }; } } ``` **规范要点：** - 使用 `@Component` 注解 - 实现 `FallbackFactory` - 记录错误日志 - 返回友好的错误信息 --- ## 九、依赖注入规范 ### 9.1 依赖注入方式选择 **Domain 层：使用构造器注入（Constructor Injection）** ```java @Component public class DeviceDomainImpl implements IDeviceDomain { private final DeviceMapper deviceMapper; public DeviceDomainImpl(DeviceMapper deviceMapper) { this.deviceMapper = deviceMapper; } } ``` **优点：** - 依赖不可变（final 字段） - 更好的可测试性 - 避免循环依赖 - 符合 Spring 官方推荐 **Service 层和 Controller 层：使用字段注入（Field Injection）** ```java @Service public class DeviceServiceImpl implements IDeviceService { @Autowired private IDeviceDomain deviceDomain; } @RestController public class DeviceController extends BaseController { @Autowired private IDeviceService deviceService; } ``` **原因：** - 代码简洁 - 符合项目现有风格 - 减少样板代码 ### 9.2 依赖注入最佳实践 1. **Domain 层必须使用构造器注入** 2. **Service 层和 Controller 层使用字段注入** 3. **避免循环依赖** 4. **依赖接口而非实现** 5. **使用 `private` 修饰注入字段** --- ## 十、命名规范 ### 10.1 包命名规范 | 层级 | 包名 | 说明 | |------|------|------| | 控制器层 | `controller` | HTTP 请求处理 | | 控制器转换 | `controller.convert` | VO ↔ DTO 转换 | | 服务接口 | `service.api` | 服务接口定义 | | 服务实现 | `service.impl` | 服务接口实现 | | 服务DTO | `service.dto` | 数据传输对象 | | 服务转换 | `service.convert` | DTO ↔ Model 转换 | | 领域接口 | `domain.api` | 领域接口定义 | | 领域实现 | `domain.impl` | 领域接口实现 | | 领域模型 | `domain.model` | 领域模型对象 | | 领域转换 | `domain.convert` | Model ↔ Entity 转换 | | 数据访问 | `mapper` | MyBatis Mapper 接口 | | 数据实体 | `mapper.entity` | 数据库实体对象 | | API视图 | `api.domain` | VO 视图对象 | | API服务 | `api` | Feign 远程服务 | | API工厂 | `api.factory` | Feign 降级工厂 | ### 10.2 类命名规范 | 类型 | 命名格式 | 示例 | |------|---------|------| | Controller | `{Entity}Controller` | `DeviceController` | | Service 接口 | `I{Entity}Service` | `IDeviceService` | | Service 实现 | `{Entity}ServiceImpl` | `DeviceServiceImpl` | | Domain 接口 | `I{Entity}Domain` | `IDeviceDomain` | | Domain 实现 | `{Entity}DomainImpl` | `DeviceDomainImpl` | | Mapper 接口 | `{Entity}Mapper` | `DeviceMapper` | | Entity 实体 | `{Entity}Entity` | `DeviceEntity` | | Domain Model | `{Entity}` | `Device` | | Service DTO | `{Entity}DTO` | `DeviceDTO` | | API VO | `{Entity}VO` | `DeviceVO` | | Domain Convert | `{Entity}DomainConvert` | `DeviceDomainConvert` | | Service Convert | `{Entity}ServiceConvert` | `DeviceServiceConvert` | | Controller Convert | `{Entity}ControllerConvert` | `DeviceControllerConvert` | | Remote Service | `Remote{Module}Service` | `RemoteDeviceService` | | Fallback Factory | `Remote{Module}FallbackFactory` | `RemoteDeviceFallbackFactory` | ### 10.3 方法命名规范 | 操作类型 | 命名格式 | 示例 | |---------|---------|------| | 查询列表 | `select{Entity}List` | `selectDeviceList` | | 查询单个 | `select{Entity}ById` | `selectDeviceById` | | 新增 | `insert{Entity}` | `insertDevice` | | 修改 | `update{Entity}` | `updateDevice` | | 删除 | `delete{Entity}ById` | `deleteDeviceById` | | 批量删除 | `delete{Entity}ByIds` | `deleteDeviceByIds` | | 转换为Entity | `toEntity` | `toEntity` | | 转换为Model | `toModel` | `toModel` | | 转换为DTO | `toDTO` | `toDTO` | | 转换为VO | `toVO` | `toVO` | | 转换为List | `toModelList`, `toDTOList`, `toVOList` | `toModelList` | ### 10.4 字段命名规范 | 字段类型 | 命名格式 | 示例 | |---------|---------|------| | 主键ID | `{entity}_id` (数据库)
`{entity}Id` (Java) | `device_id`
`deviceId` | | 普通字段 | `field_name` (数据库)
`fieldName` (Java) | `device_name`
`deviceName` | | 外键字段 | `{ref_entity}_id` (数据库)
`{refEntity}Id` (Java) | `dock_id`
`dockId` | | 布尔字段 | `is_{field}` (数据库)
`is{Field}` (Java) | `is_active`
`isActive` | | 时间字段 | `{action}_time` (数据库)
`{action}Time` (Java) | `create_time`
`createTime` | ### 10.5 数据库命名规范 | 对象类型 | 命名格式 | 示例 | |---------|---------|------| | 表名 | `{module}_{table}` | `device_device`, `device_dock` | | 主键 | `{table}_id` | `device_id`, `dock_id` | | 普通索引 | `idx_{table}_{field}` | `idx_dock_device_id` | | 唯一索引 | `uk_{table}_{field}` | `uk_device_sn` | | 复合索引 | `idx_{table}_{field1}_{field2}` | `idx_dock_device_status` | | Flyway历史表 | `flyway_{module}_schema_history` | `flyway_device_schema_history` | --- ## 十一、对象转换流程 ### 11.1 数据流转图 ``` 前端请求 ↓ Controller 接收 VO ↓ ControllerConvert.toDTO(vo) Service 处理 DTO ↓ ServiceConvert.toModel(dto) Domain 处理 Model ↓ DomainConvert.toEntity(model) Mapper 操作 Entity ↓ 数据库 Database ↑ Mapper 返回 Entity ↑ DomainConvert.toModel(entity) Domain 返回 Model ↑ ServiceConvert.toDTO(model) Service 返回 DTO ↑ ControllerConvert.toVO(dto) Controller 返回 VO ↑ 前端响应 ``` ### 11.2 对象职责说明 | 对象类型 | 所属层 | 职责 | 特点 | |---------|-------|------|------| | **VO** (View Object) | API层 | 前后端数据交互 | 可包含展示逻辑字段 | | **DTO** (Data Transfer Object) | Service层 | 业务逻辑编排 | 可包含业务组合字段 | | **Model** | Domain层 | 领域业务逻辑 | 纯业务模型 | | **Entity** | Mapper层 | 数据库映射 | 与数据库表一一对应 | ### 11.3 转换类职责 | 转换类 | 转换方向 | 位置 | |-------|---------|------| | **ControllerConvert** | VO ↔ DTO | `controller.convert` | | **ServiceConvert** | DTO ↔ Model | `service.convert` | | **DomainConvert** | Model ↔ Entity | `domain.convert` | --- ## 十二、最佳实践 ### 12.1 代码规范 1. **分层清晰**：严格遵守 Controller → Service → Domain → Mapper 分层 2. **单一职责**：每个类只负责一个职责 3. **依赖倒置**：依赖接口而非实现 4. **对象转换**：使用专门的 Convert 类进行对象转换 5. **异常处理**：使用统一的异常处理机制 6. **日志记录**：关键操作必须记录日志 7. **权限控制**：Controller 方法必须添加权限注解 ### 12.2 数据库规范 1. **表名规范**：`{module}_{table}` 格式 2. **主键规范**：`{table}_id`，BIGINT，AUTO_INCREMENT 3. **BaseEntity字段**：所有表必须包含 create_by, create_time, update_by, update_time, remark 4. **索引规范**：外键字段必须添加索引 5. **字符集**：统一使用 utf8mb4 6. **存储引擎**：统一使用 InnoDB 7. **Flyway迁移**：所有数据库变更必须通过 Flyway 脚本 ### 12.3 配置规范 1. **端口分配**： - 基础服务：9200-9209 - 业务服务：9210-9299 - 监控服务：9100 - 特殊服务：9300+ 2. **配置同步**： - bootstrap.yml 的 server.port 必须与 docker-compose.yml 的容器端口一致 - Flyway 历史表名格式：`flyway_{module}_schema_history` 3. **服务命名**： - 服务名称格式：`{module-name}` - 在 ServiceNameConstants 中定义常量 ### 12.4 API 规范 1. **Feign 客户端**： - 接口命名：`Remote{Module}Service` - contextId：`remote{Module}Service` - 必须配置 fallbackFactory 2. **降级处理**： - 工厂命名：`Remote{Module}FallbackFactory` - 必须记录错误日志 - 返回友好的错误信息 3. **安全头**： - 所有 Feign 方法必须包含 `@RequestHeader(SecurityConstants.FROM_SOURCE) String source` ### 12.5 Maven 规范 1. **新增服务步骤**： - 在 ServiceNameConstants 中添加服务名常量 - 在根 pom.xml 的 dependencyManagement 中添加 API 依赖 - 在 ruoyi-api/pom.xml 中添加模块声明 - 创建业务模块和 API 模块 2. **依赖管理**： - 版本号统一在根 pom.xml 管理 - 使用 `${ruoyi.version}` 引用版本 ### 12.6 开发流程 1. **数据库设计** → 编写 Flyway 迁移脚本 2. **Mapper 层** → Entity + Mapper 接口 + Mapper XML 3. **Domain 层** → Model + Domain 接口 + Domain 实现 + Domain Convert 4. **Service 层** → DTO + Service 接口 + Service 实现 + Service Convert 5. **Controller 层** → Controller + Controller Convert 6. **API 层** → VO + Remote Service + Fallback Factory 7. **配置** → bootstrap.yml + docker-compose.yml 8. **测试** → 单元测试 + 集成测试 --- ## 附录：快速参考 ### A. 创建新模块检查清单 - [ ] 数据库表设计（遵循命名规范） - [ ] Flyway 迁移脚本（V{版本号}__{描述}.sql） - [ ] Entity 实体类（继承 BaseEntity） - [ ] Mapper 接口和 XML - [ ] Domain Model（领域模型） - [ ] Domain 接口和实现（构造器注入） - [ ] Domain Convert（对象转换） - [ ] Service DTO（数据传输对象） - [ ] Service 接口和实现（字段注入） - [ ] Service Convert（对象转换） - [ ] Controller（权限控制、日志记录） - [ ] Controller Convert（对象转换） - [ ] API VO（视图对象） - [ ] Remote Service（Feign 客户端） - [ ] Fallback Factory（降级处理） - [ ] ServiceNameConstants（服务名常量） - [ ] 根 pom.xml（依赖管理） - [ ] ruoyi-api/pom.xml（模块声明） - [ ] bootstrap.yml（端口配置） - [ ] docker-compose.yml（容器配置） ### B. 常见问题 **Q: 为什么 Domain 层使用构造器注入，Service 层使用字段注入？** A: Domain 层使用构造器注入是为了保证依赖不可变和更好的可测试性；Service 层使用字段注入是为了代码简洁和符合项目现有风格。 **Q: 为什么需要这么多对象（VO、DTO、Model、Entity）？** A: 不同层次的对象有不同的职责，这样可以实现关注点分离，提高代码的可维护性和可扩展性。 **Q: Convert 类为什么使用静态方法？** A: Convert 类是无状态的工具类，使用静态方法可以避免不必要的对象创建，提高性能。 **Q: 如何处理端口冲突？** A: 按照端口分配规范，基础服务使用 9200-9209，业务服务使用 9210-9299，确保 bootstrap.yml 和 docker-compose.yml 中的端口配置一致。 **Q: Flyway 迁移脚本命名有什么要求？** A: 格式为 `V{版本号}__{描述}.sql`，版本号从1开始递增不能跳号，描述使用下划线分隔的英文，首字母大写。 --- **文档结束** > 本文档将持续更新，如有疑问或建议，请联系架构团队。