# 数字孪生项目开发规范

## 1. 技术栈与框架版本

### 1.1 核心技术栈
- **Java 版本**: 1.8 (已升级)
- **Spring Boot**: 2.3.12.RELEASE
- **MyBatis-Plus**: 3.x
- **数据库**: PostgreSQL (PostGIS 扩展)
- **注册中心/配置中心**: Nacos
- **日志框架**: Logback + Slf4j
- **JSON 处理**: Jackson
- **工具库**: Hutool 5.7.7, Guava 31.1-jre
- **Lombok**: 用于简化实体类
- **定时任务**: 定时任务采用 xxl-job，位于每个模块的 job 下面

### 1.2 构建工具
- **Maven**: 3.9.6
- **Maven 编译器插件**: 3.8.1

## 2. 项目结构规范

### 2.1 模块划分
```
digital-twins-vapor/
├── dt-vapor-common/ # 公共模块
├── dt-vapor-bus/ # 业务服务模块
├── dt-vapor-core/ # 核心服务模块
├── dt-vapor-etl/ # ETL 数据处理模块
├── dt-vapor-gis/ # GIS 地理信息模块
```

### 2.2 包结构规范
```
com.vapor.digital.twin.{模块名}/
├── controller/ # 控制器层
│ ├── {业务}/request/ # 请求 DTO
│ ├── {业务}/vo/ # 返回 VO
│ └── {业务}Controller.java
├── service/ # 服务层
│ ├── {业务}Service.java # 服务接口
│ └── impl/ # 服务实现
├── domain/ # 业务领域层
├── repo/ # 数据访问层
│ ├── mapper/ # MyBatis Mapper
│ └── po/ # 持久化对象
├── config/ # 配置类
├── enums/ # 枚举类
└── utils/ # 工具类
```

## 3. 编码规范

### 3.1 命名规范
- **包名**: 全小写，使用域名反写 `com.vapor.digital.twin`
- **类名**: 大驼峰命名，如 `UserController`, `AlarmInfoVO`
- **方法名**: 小驼峰命名，如 `getUserById()`, `calculatePressure()`
- **常量**: 全大写，下划线分隔，如 `MAX_ALLOWABLE_PRESSURE`
- **变量名**: 小驼峰命名，如 `userName`, `nodeCode`

### 3.2 代码注释规范
```java
/**
* 类功能描述
* @ClassName ClassName
* @Description 详细描述
* @Author 作者名
* @Date 日期时间
* @Version 版本号
**/
```

### 3.3 枚举类规范
```java
@Getter
public enum EnumName {
TYPE_CODE("CODE", "描述");

@EnumValue
private final String code;
private final String msg;

public static EnumName getByCode(String code) {
// 实现代码
}
}
```

## 4. 日志规范

### 4.1 日志配置
- 使用 Logback 配置文件: `logback.xml`
- 日志文件路径: `logs/{appName}.log`
- 日志文件大小限制: 32MB
- 历史日志保留: 30 天
- 总日志大小限制: 1GB

### 4.2 日志级别
```yaml
logging:
level:
com.vapor.digital.twin: info
com.vapor.digital.twin.repo.mapper: debug # SQL 日志
com.vapor.digital.twin.service: debug # 业务日志
```

### 4.3 日志格式
```
%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level --- [%15.15(%thread)] %-40.40(%logger{40}) : %msg%n
```

## 5. 异常处理规范

### 5.1 统一异常处理
使用 `@RestControllerAdvice` 实现全局异常处理:
- **业务异常**: `BizException` (code=100)
- **参数验证异常**: `MethodArgumentNotValidException`
- **绑定异常**: `BindException`

### 5.2 业务异常定义
```java
public class BizException extends RuntimeException {
private String code = "100"; // 默认错误码
private String eMsg; // 扩展信息
}
```

### 5.3 断言工具类
使用 `AssertUtils` 进行参数校验:
```java
AssertUtils.assertEmptyThrow(param, "参数不能为空");
AssertUtils.assertPatternThrow(date, REGEX_YYYY_MM_DD, "日期格式错误");
```

## 6. 接口规范

### 6.1 统一返回格式
```java
public class Result {
private String code; // 返回编码: 200 成功, 100 错误, 201 处理中
private T data; // 返回数据
private String msg; // 用户消息
private String sysMsg; // 系统消息
}
```

### 6.2 控制器规范
```java
@RestController
@RequestMapping("/{业务模块}")
@Slf4j
@RequiredArgsConstructor
public class Controller {

@PostMapping("/{操作}")
public Result method(@RequestBody RequestDTO req) {
// 业务逻辑
return Result.success(data);
}
}
```

### 6.3 日期格式规范
- 请求参数: `@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")`
- JSON 序列化: `@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")`

## 7. 数据库规范

### 7.1 实体类规范
- 继承基类: `BasePO` 或 `BaseWithoutProjectPO`
- 使用 Lombok 注解: `@Data`, `@NoArgsConstructor`, `@AllArgsConstructor`
- 自动映射注解: `@AutoMapper(target = TargetClass.class)`

### 7.2 MyBatis-Plus 配置
```yaml
mybatis-plus:
configuration:
default-enum-type-handler: com.baomidou.mybatisplus.core.handlers.MybatisEnumTypeHandler
call-setters-on-nulls: true
cache-enabled: false
local-cache-scope: statement
global-config:
db-config:
update-strategy: not_null # 只更新非 null 字段
```

### 7.3 分页规范
使用 MyBatis-Plus 分页插件:
```java
Page page = new Page<>(current, size);
IPage result = mapper.selectPage(page, queryWrapper);
```

### 7.4 多租户支持
- 租户字段: `tenant_code`
- 项目字段: `project_code`
- 使用租户拦截器: `TenantLineInnerInterceptor`

## 8. 配置规范

### 8.1 配置文件结构
```yaml
## =================《自定义配置信息，注意：允许开发人员增删改》================================
# 开发人员自定义配置
config_center_ip_port: ip:port
config_center_namespace: namespace
config_center_group: group

## =================《本地环境系统配置，注意：不允许修改》======================================
# 配置中心配置
nacos:
config:
server-addr: ${config_center_ip_port}
namespace: ${config_center_namespace}
group: ${config_center_group}

# 注册中心配置
spring:
cloud:
nacos:
discovery:
server-addr: localhost:8848

# 日志级别配置
logging:
level:
com.vapor.digital.twin: debug
```

### 8.2 环境配置
- **本地环境**: `application-local.yml`
- **开发环境**: `application-dev.yml`
- **测试环境**: `application-beta.yml`
- **生产环境**: `application-prod.yml`

## 9. 安全规范

### 9.1 敏感信息处理
- 数据库密码、API 密钥等使用配置中心管理
- 日志中禁止打印敏感信息
- 使用脱敏注解处理返回数据

### 9.2 接口安全
- 重要接口需要鉴权
- 参数需要进行合法性校验
- 防止 SQL 注入、XSS 攻击

## 10. 部署规范

### 10.1 服务端口
- dt-vapor-bus: 38881
- 其他模块按顺序分配端口

### 10.2 JVM 参数
```bash
-Xms512m -Xmx1024m -XX:+UseG1GC -XX:+PrintGCDetails -XX:+PrintGCTimeStamps
```

### 10.3 健康检查
- 提供 `/actuator/health` 端点
- 数据库连接检查
- 外部服务依赖检查

## 11. 代码审查要点

### 11.1 必须检查项
- [ ] 是否遵循命名规范
- [ ] 是否有适当的注释
- [ ] 异常处理是否完善
- [ ] 日志打印是否合理
- [ ] SQL 是否有性能问题
- [ ] 是否存在安全漏洞
- [ ] 方法内部代码不能 try catch 直接嵌套
- [ ] 不准使用 swagger api
- [ ] 紧张循环访问数据库

### 11.2 推荐检查项
- [ ] 代码复用性
- [ ] 单元测试覆盖率
- [ ] 接口文档完整性
- [ ] 配置是否合理

## 12. 常见问题处理

### 12.1 版本兼容性问题
- Java 24 兼容性已处理
- Maven 插件版本需要匹配
- 依赖冲突使用 `` 解决

### 12.2 性能优化建议
- 使用分页查询避免全表扫描
- 合理使用索引
- 缓存热点数据
- 异步处理耗时操作

---

**最后更新**: 2025 年
**维护者**: 项目开发团队