pipe-ner-server/.feisuan/rules/project_rule.md

开发规范指南

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

一、项目基本信息

• 工作目录：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 架构，包含网关、公共模块及多个业务服务模块。

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 等