# 开发规范指南
为保证代码质量、可维护性、安全性与可扩展性，请在开发过程中严格遵循以下规范。

## 一、项目基本信息

- **工作目录**：`E:\work\pipe-ner-server`
- **代码作者**：Administrator
- **构建工具**：Maven
- **JDK 版本**：Java 11 (JDK 11.0.27)
- **核心框架**：Spring Boot 2.7.12
- **微服务架构**：Spring Cloud 2021.0.3 + Spring Cloud Alibaba 2021.0.4.0

## 二、项目目录结构

本项目采用多模块 Maven 架构，包含网关、公共模块及多个业务服务模块。

```text
pipe-ner-server
├── audio-service                 # 音频服务
├── docs                          # 文档
├── environment-service           # 环境服务
├── firefighting-pressure-service # 消防压力服务
├── flammable-gas-service         # 易燃气体服务
├── manhole-service               # 井盖服务
├── pipe-network-service          # 管网核心服务
│   ├── zksy-admin                # Web服务入口
│   ├── zksy-common               # 通用工具
│   ├── zksy-framework            # 框架核心
│   ├── zksy-generator            # 代码生成
│   ├── zksy-quartz               # 定时任务
│   └── zksy-system               # 系统模块
├── radar-service                 # 雷达服务
├── telemetry-service             # 遥测服务
├── water-level-service           # 水位服务
├── zk-api-service                # API服务
├── zk-common                     # 公共模块
└── zk-gateway                    # 网关服务
```

## 三、技术栈要求

- **主框架**：Spring Boot 2.7.12
- **语言版本**：Java 11
- **数据库**：KingbaseES (人大金仓) / MySQL
- **ORM框架**：MyBatis-Plus 3.5.7
- **核心依赖**：
  - `spring-boot-starter-web`
  - `mybatis-plus-boot-starter`
  - `lombok`
  - `hutool-all` (工具类库)
  - `spring-cloud-starter-alibaba-nacos` (注册中心/配置中心)
  - `spring-cloud-starter-alibaba-sentinel` (熔断限流)
  - `knife4j-openapi2-spring-boot-starter` (API文档)

## 四、分层架构规范

| 层级        | 职责说明                         | 开发约束与注意事项                                               |
|-------------|----------------------------------|----------------------------------------------------------------|
| **Controller** | 处理 HTTP 请求与响应，定义 API 接口 | 使用 `@RestController`；不得包含业务逻辑，仅负责参数校验和结果封装 |
| **Service**    | 实现业务逻辑、事务管理与数据校验   | 接口定义在 `service` 包，实现类放在 `service.impl` 包；事务注解 `@Transactional` 仅在此层使用 |
| **Mapper**     | 数据库访问与持久化操作             | 继承 `BaseMapper`；对应 XML 文件需放在 `resources/mapper` 目录下 |
| **Domain/Entity** | 映射数据库表结构及数据传输对象     | 实体类建议放在 `domain` 包；DTO/VO/Query 对象按职责定义          |

### 接口与实现分离

- 所有 Service 接口实现类需放在接口所在包下的 `impl` 子包中。

## 五、安全与性能规范

### 输入校验

- 使用 `@Valid` 与 JSR-303 校验注解（如 `@NotBlank`, `@Size` 等）
  - **注意**：Spring Boot 2.x 中校验注解位于 `javax.validation.constraints.*`
- 禁止在 XML 文件中使用 `${}` 拼接 SQL，防止 SQL 注入，必须使用 `#{}`。

### 事务管理

- `@Transactional` 注解仅用于 **Service 层**方法。
- 避免在循环中频繁提交事务，影响性能。

## 六、代码风格规范

### 命名规范

| 类型       | 命名方式             | 示例                  |
|------------|----------------------|-----------------------|
| 类名       | UpperCamelCase       | `UserServiceImpl`     |
| 方法/变量  | lowerCamelCase       | `saveUser()`          |
| 常量       | UPPER_SNAKE_CASE     | `MAX_LOGIN_ATTEMPTS`  |

### 注释规范

- 所有类、接口、公共方法需添加 **Javadoc** 注释。
- **注释语言**：必须使用中文（用户第一语言）。
- 作者信息统一填写：`@author Administrator`

### 类型命名规范（阿里巴巴风格）

| 后缀 | 用途说明                     | 示例         |
|------|------------------------------|--------------|
| DTO  | 数据传输对象                 | `UserDTO`    |
| Entity/DO   | 数据库实体对象               | `UserDO`     |
| BO   | 业务逻辑封装对象             | `UserBO`     |
| VO   | 视图展示对象                 | `UserVO`     |
| Query| 查询参数封装对象             | `UserQuery`  |

### 实体类简化工具

- 使用 Lombok 注解替代手动编写 getter/setter/构造方法：
  - `@Data`
  - `@NoArgsConstructor`
  - `@AllArgsConstructor`
  - `@Builder` (如需链式调用)

## 七、扩展性与日志规范

### 接口优先原则

- 所有业务逻辑通过接口定义（如 `UserService`），具体实现放在 `impl` 包中（如 `UserServiceImpl`）。

### 日志记录

- 使用 `@Slf4j` 注解代替 `System.out.println`。
- 日志级别规范：开发环境使用 DEBUG，生产环境使用 INFO 或 WARN。

### 工具类使用

- 优先使用 `hutool-all` 工具包中的工具类（如 `StrUtil`, `CollUtil` 等），避免重复造轮子。
- 日期处理优先使用 `java.time` 包下的类。

## 八、编码原则总结

| 原则       | 说明                                       |
|------------|--------------------------------------------|
| **SOLID**  | 高内聚、低耦合，增强可维护性与可扩展性     |
| **DRY**    | 避免重复代码，提高复用性                   |
| **KISS**   | 保持代码简洁易懂                           |
| **YAGNI**  | 不实现当前不需要的功能                     |
| **OWASP**  | 防范常见安全漏洞，如 SQL 注入、XSS 等      |