2029 lines
56 KiB
Markdown
2029 lines
56 KiB
Markdown
# 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` 的 `<dependencyManagement>` 中添加：
|
||
|
||
```xml
|
||
<!-- {模块中文名}接口 -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>{module-name}-api-{submodule}</artifactId>
|
||
<version>${ruoyi.version}</version>
|
||
</dependency>
|
||
```
|
||
|
||
**示例：**
|
||
```xml
|
||
<!-- 设备接口 -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>tuoheng-api-device</artifactId>
|
||
<version>${ruoyi.version}</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2.2 ruoyi-api/pom.xml 配置
|
||
|
||
在 `ruoyi-api/pom.xml` 的 `<modules>` 中添加：
|
||
|
||
```xml
|
||
<module>{module-name}-api-{submodule}</module>
|
||
```
|
||
|
||
**示例：**
|
||
```xml
|
||
<modules>
|
||
<module>ruoyi-api-system</module>
|
||
<module>tuoheng-api-device</module>
|
||
<module>tuoheng-api-airline</module>
|
||
</modules>
|
||
```
|
||
|
||
### 2.3 业务模块 pom.xml 标准配置
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xmlns="http://maven.apache.org/POM/4.0.0"
|
||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||
<parent>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-modules</artifactId>
|
||
<version>3.6.7</version>
|
||
</parent>
|
||
<modelVersion>4.0.0</modelVersion>
|
||
|
||
<artifactId>{module-name}</artifactId>
|
||
|
||
<description>
|
||
{module-name}系统模块
|
||
</description>
|
||
|
||
<dependencies>
|
||
<!-- {Module} API -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>{module-name}-api-{submodule}</artifactId>
|
||
</dependency>
|
||
|
||
<!-- SpringCloud Alibaba Nacos -->
|
||
<dependency>
|
||
<groupId>com.alibaba.cloud</groupId>
|
||
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
|
||
</dependency>
|
||
|
||
<!-- SpringCloud Alibaba Nacos Config -->
|
||
<dependency>
|
||
<groupId>com.alibaba.cloud</groupId>
|
||
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
|
||
</dependency>
|
||
|
||
<!-- SpringCloud Alibaba Sentinel -->
|
||
<dependency>
|
||
<groupId>com.alibaba.cloud</groupId>
|
||
<artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
|
||
</dependency>
|
||
|
||
<!-- SpringBoot Actuator -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-actuator</artifactId>
|
||
</dependency>
|
||
|
||
<!-- Mysql Connector -->
|
||
<dependency>
|
||
<groupId>com.mysql</groupId>
|
||
<artifactId>mysql-connector-j</artifactId>
|
||
</dependency>
|
||
|
||
<!-- RuoYi Common DataSource -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-common-datasource</artifactId>
|
||
</dependency>
|
||
|
||
<!-- RuoYi Common DataScope -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-common-datascope</artifactId>
|
||
</dependency>
|
||
|
||
<!-- RuoYi Common Log -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-common-log</artifactId>
|
||
</dependency>
|
||
|
||
<!-- RuoYi Common Swagger -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-common-swagger</artifactId>
|
||
</dependency>
|
||
|
||
<!-- Flyway Database Migration -->
|
||
<dependency>
|
||
<groupId>org.flywaydb</groupId>
|
||
<artifactId>flyway-core</artifactId>
|
||
</dependency>
|
||
|
||
<!-- Flyway MySQL Support -->
|
||
<dependency>
|
||
<groupId>org.flywaydb</groupId>
|
||
<artifactId>flyway-mysql</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
|
||
<build>
|
||
<finalName>${project.artifactId}</finalName>
|
||
<plugins>
|
||
<plugin>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||
<executions>
|
||
<execution>
|
||
<goals>
|
||
<goal>repackage</goal>
|
||
</goals>
|
||
</execution>
|
||
</executions>
|
||
</plugin>
|
||
</plugins>
|
||
</build>
|
||
</project>
|
||
```
|
||
|
||
### 2.4 API 模块 pom.xml 标准配置
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xmlns="http://maven.apache.org/POM/4.0.0"
|
||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||
<parent>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-api</artifactId>
|
||
<version>3.6.7</version>
|
||
</parent>
|
||
<modelVersion>4.0.0</modelVersion>
|
||
|
||
<artifactId>{module-name}-api-{submodule}</artifactId>
|
||
|
||
<description>
|
||
{module-name} API模块
|
||
</description>
|
||
|
||
<dependencies>
|
||
<!-- RuoYi Common Core -->
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>ruoyi-common-core</artifactId>
|
||
</dependency>
|
||
|
||
<!-- Spring Cloud OpenFeign -->
|
||
<dependency>
|
||
<groupId>org.springframework.cloud</groupId>
|
||
<artifactId>spring-cloud-starter-openfeign</artifactId>
|
||
</dependency>
|
||
</dependencies>
|
||
</project>
|
||
```
|
||
|
||
---
|
||
|
||
## 三、配置文件规范
|
||
|
||
### 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
|
||
<?xml version="1.0" encoding="UTF-8" ?>
|
||
<!DOCTYPE mapper
|
||
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
|
||
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
|
||
<mapper namespace="com.ruoyi.{module}.mapper.{Entity}Mapper">
|
||
|
||
<resultMap type="com.ruoyi.{module}.mapper.entity.{Entity}Entity" id="{Entity}Result">
|
||
<result property="{entity}Id" column="{entity}_id" />
|
||
<result property="fieldName" column="field_name" />
|
||
<result property="createBy" column="create_by" />
|
||
<result property="createTime" column="create_time" />
|
||
<result property="updateBy" column="update_by" />
|
||
<result property="updateTime" column="update_time" />
|
||
<result property="remark" column="remark" />
|
||
</resultMap>
|
||
|
||
<sql id="select{Entity}Vo">
|
||
select {entity}_id, field_name, create_by, create_time, update_by, update_time, remark
|
||
from {module}_{table}
|
||
</sql>
|
||
|
||
<select id="select{Entity}List" parameterType="com.ruoyi.{module}.mapper.entity.{Entity}Entity" resultMap="{Entity}Result">
|
||
<include refid="select{Entity}Vo"/>
|
||
<where>
|
||
<if test="{entity}Id != null"> and {entity}_id = #{{{entity}Id}}</if>
|
||
<if test="fieldName != null and fieldName != ''"> and field_name like concat('%', #{fieldName}, '%')</if>
|
||
</where>
|
||
</select>
|
||
|
||
<select id="select{Entity}ById" parameterType="Long" resultMap="{Entity}Result">
|
||
<include refid="select{Entity}Vo"/>
|
||
where {entity}_id = #{{{entity}Id}}
|
||
</select>
|
||
|
||
<insert id="insert{Entity}" parameterType="com.ruoyi.{module}.mapper.entity.{Entity}Entity" useGeneratedKeys="true" keyProperty="{entity}Id" keyColumn="{entity}_id">
|
||
insert into {module}_{table}
|
||
<trim prefix="(" suffix=")" suffixOverrides=",">
|
||
<if test="fieldName != null and fieldName != ''">field_name,</if>
|
||
<if test="createBy != null and createBy != ''">create_by,</if>
|
||
<if test="remark != null">remark,</if>
|
||
create_time
|
||
</trim>
|
||
<trim prefix="values (" suffix=")" suffixOverrides=",">
|
||
<if test="fieldName != null and fieldName != ''">#{fieldName},</if>
|
||
<if test="createBy != null and createBy != ''">#{createBy},</if>
|
||
<if test="remark != null">#{remark},</if>
|
||
sysdate()
|
||
</trim>
|
||
</insert>
|
||
|
||
<update id="update{Entity}" parameterType="com.ruoyi.{module}.mapper.entity.{Entity}Entity">
|
||
update {module}_{table}
|
||
<trim prefix="SET" suffixOverrides=",">
|
||
<if test="fieldName != null and fieldName != ''">field_name = #{fieldName},</if>
|
||
<if test="updateBy != null and updateBy != ''">update_by = #{updateBy},</if>
|
||
<if test="remark != null">remark = #{remark},</if>
|
||
update_time = sysdate()
|
||
</trim>
|
||
where {entity}_id = #{{{entity}Id}}
|
||
</update>
|
||
|
||
<delete id="delete{Entity}ById" parameterType="Long">
|
||
delete from {module}_{table} where {entity}_id = #{{{entity}Id}}
|
||
</delete>
|
||
|
||
<delete id="delete{Entity}ByIds" parameterType="Long">
|
||
delete from {module}_{table} where {entity}_id in
|
||
<foreach item="{entity}Id" collection="array" open="(" separator="," close=")">
|
||
#{{{entity}Id}}
|
||
</foreach>
|
||
</delete>
|
||
|
||
</mapper>
|
||
```
|
||
|
||
**规范要点：**
|
||
- 使用 `<resultMap>` 定义结果映射
|
||
- 使用 `<sql>` 定义可复用的 SQL 片段
|
||
- 使用动态 SQL 标签：`<if>`, `<trim>`, `<foreach>`
|
||
- 插入操作使用 `useGeneratedKeys="true"` 返回主键
|
||
- **重要**：插入操作必须同时指定 `keyProperty` 和 `keyColumn` 属性
|
||
- 时间字段使用 `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});
|
||
int result = {entity}Mapper.insert{Entity}(entity);
|
||
// 【重要】MyBatis 会将自增主键回填到 entity 对象，需要同步回 model 对象
|
||
{entity}.set{Entity}Id(entity.get{Entity}Id());
|
||
return result;
|
||
}
|
||
|
||
@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 类进行对象转换
|
||
- **【关键】insert 方法必须将 Entity 的主键回填到 Model 对象**
|
||
|
||
**⚠️ MyBatis 主键回填注意事项：**
|
||
|
||
MyBatis 在执行 INSERT 操作后，会将数据库自动生成的主键值回填到 `Entity` 对象中，但**不会自动同步到传入的 `Model` 对象**。
|
||
|
||
**错误示例（会导致主键丢失）：**
|
||
```java
|
||
@Override
|
||
public int insert{Entity}({Entity} {entity})
|
||
{
|
||
{Entity}Entity entity = {Entity}DomainConvert.toEntity({entity});
|
||
return {entity}Mapper.insert{Entity}(entity);
|
||
// ❌ 错误：entity 中的主键没有同步回 {entity} 对象
|
||
}
|
||
```
|
||
|
||
**正确示例（主键正确回填）：**
|
||
```java
|
||
@Override
|
||
public int insert{Entity}({Entity} {entity})
|
||
{
|
||
{Entity}Entity entity = {Entity}DomainConvert.toEntity({entity});
|
||
int result = {entity}Mapper.insert{Entity}(entity);
|
||
// ✅ 正确：将 entity 中的主键同步回 {entity} 对象
|
||
{entity}.set{Entity}Id(entity.get{Entity}Id());
|
||
return result;
|
||
}
|
||
```
|
||
|
||
**为什么需要手动同步主键？**
|
||
|
||
1. **对象转换导致的隔离**：`BeanUtils.copyProperties()` 只是属性拷贝，创建了新的 Entity 对象
|
||
2. **MyBatis 只回填 Entity**：MyBatis 的 `useGeneratedKeys` 只会将主键设置到 Mapper 方法参数（Entity）中
|
||
3. **Model 对象不会自动更新**：原始的 Model 对象与 Entity 对象是两个独立的对象，需要手动同步
|
||
|
||
**不同步主键的后果：**
|
||
|
||
如果不将主键同步回 Model 对象，会导致：
|
||
- Service 层无法获取新插入记录的主键 ID
|
||
- 后续依赖主键的业务逻辑会失败（如关联表插入）
|
||
- 可能产生重复数据或数据不一致问题
|
||
|
||
**示例场景：**
|
||
```java
|
||
// Service 层调用
|
||
Device device = new Device();
|
||
device.setDeviceName("测试设备");
|
||
deviceDomain.insertDevice(device);
|
||
|
||
// 如果没有主键回填，device.getDeviceId() 将返回 null
|
||
Long deviceId = device.getDeviceId(); // 期望得到新插入的 ID
|
||
|
||
// 后续业务逻辑依赖这个 ID
|
||
Dock dock = new Dock();
|
||
dock.setDeviceId(deviceId); // 如果 deviceId 为 null，会导致关联失败
|
||
dockDomain.insertDock(dock);
|
||
```
|
||
|
||
|
||
### 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<Remote{Module}Service>
|
||
{
|
||
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<Remote{Module}Service>`
|
||
- 记录错误日志
|
||
- 返回友好的错误信息
|
||
|
||
---
|
||
|
||
## 九、依赖注入规范
|
||
|
||
### 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` (数据库) <br> `{entity}Id` (Java) | `device_id` <br> `deviceId` |
|
||
| 普通字段 | `field_name` (数据库) <br> `fieldName` (Java) | `device_name` <br> `deviceName` |
|
||
| 外键字段 | `{ref_entity}_id` (数据库) <br> `{refEntity}Id` (Java) | `dock_id` <br> `dockId` |
|
||
| 布尔字段 | `is_{field}` (数据库) <br> `is{Field}` (Java) | `is_active` <br> `isActive` |
|
||
| 时间字段 | `{action}_time` (数据库) <br> `{action}Time` (Java) | `create_time` <br> `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开始递增不能跳号，描述使用下划线分隔的英文，首字母大写。
|
||
|
||
---
|
||
|
||
**文档结束**
|
||
|
||
> 本文档将持续更新，如有疑问或建议，请联系架构团队。
|