GeoHazardMonitor/.feisuan/rules/project_rule.md

开发规范指南

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

一、项目基本信息

• 工作目录: D:\地址灾害\GeoHazardMonitor
• 项目名称: GeoHazardMonitor
• 开发者: Administrator
• 第一语言: 中文（注释使用中文）

二、技术栈要求

• 主框架: Spring Boot 2.5.14
• 语言版本: Java 1.8
• 构建工具: Maven
• 数据库驱动: MySQL Connector/J
• 持久层框架: MyBatis Plus
• 缓存中间件: Redis
• MQTT客户端: Eclipse Paho Client
• 消息队列: RabbitMQ (AMQP)
• 序列化库: FastJSON
• 其他依赖:
  • Lombok
  • Druid 数据库连接池
  • MinIO 客户端
  • Hutool 工具类库

三、目录结构说明

GeoHazardMonitor
├── business-service
│   └── src
│       ├── main
│       │   ├── java
│       │   │   └── com
│       │   │       └── ozs
│       │   │           └── service
│       │   │               ├── entity
│       │   │               │   └── vo
│       │   │               ├── mapper
│       │   │               ├── params
│       │   │               ├── service
│       │   │               │   └── impl
│       │   │               └── utils
│       │   └── resources
│       │       └── mapper
│       │           └── service
│       └── test
│           └── java
│               └── com
│                   └── ozs
│                       └── service
│                           └── test
├── hazard-admin
│   └── src
│       └── main
│           ├── java
│           │   └── com
│           │       └── ozs
│           │           └── web
│           │               ├── controller
│           │               │   ├── accountmanagment
│           │               │   ├── app
│           │               │   ├── common
│           │               │   ├── home
│           │               │   ├── monitor
│           │               │   ├── mqtt
│           │               │   ├── shotschedule
│           │               │   ├── system
│           │               │   ├── tool
│           │               │   ├── upload
│           │               │   └── websocket
│           │               └── core
│           │                   ├── config
│           │                   ├── init
│           │                   └── util
│           └── resources
│               ├── i18n
│               ├── META-INF
│               ├── mybatis
│               └── template
└── hazard-sdk
    └── src
        └── main
            ├── java
            │   └── com
            │       └── ozs
            │           ├── config
            │           │   ├── datasource
            │           │   └── properties
            │           ├── controller
            │           │   └── upload
            │           ├── jpush
            │           ├── vo
            │           └── websocket
            └── resources
                ├── i18n
                ├── META-INF
                └── mybatis

四、分层架构规范

层级	职责说明	开发约束与注意事项
Controller	处理 HTTP 请求与响应，定义 API 接口	不得直接访问数据库，必须通过 Service 层调用
Service	实现业务逻辑、事务管理与数据校验	必须通过 Repository 层访问数据库；返回 DTO 而非 Entity（除非必要）
Repository	数据库访问与持久化操作	继承 BaseMapper 或使用 MyBatis Plus 提供的方法避免 N+1 查询问题
Entity	映射数据库表结构	不得直接返回给前端（需转换为 DTO）；包名统一为 entity

接口与实现分离

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

五、安全与性能规范

输入校验

• 使用 @Valid 与 JSR-303 校验注解（如 @NotBlank, @Size 等）

  • 注意：Spring Boot 2.x 中校验注解位于 javax.validation.constraints.*

• 禁止手动拼接 SQL 字符串，防止 SQL 注入攻击。

事务管理

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

六、代码风格规范

命名规范

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

注释规范

• 所有类、方法、字段需添加 Javadoc 注释，并使用中文注释。

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

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

实体类简化工具

• 使用 Lombok 注解替代手动编写 getter/setter/构造方法：
  • @Data
  • @NoArgsConstructor
  • @AllArgsConstructor

七、扩展性与日志规范

接口优先原则

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

日志记录

• 使用 @Slf4j 注解代替 System.out.println

八、编码原则总结

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