
# 开发规范指南

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

## 一、项目基本信息

- **工作目录**：`D:\IDEA2024\HazMatSpider`
- **项目作者**：xiongwanxiong
- **操作系统**：Windows 11
- **当前时间**：2025-11-26 09:27:58

## 二、技术栈要求

- **主框架**：Spring Boot 2.5.15
- **语言版本**：Java 1.8
- **构建工具**：Maven
- **SDK版本**：JDK 1.8.0_231
- **数据库**：MySQL 8.0
- **前端框架**：Vue 3 + Element Plus

## 三、目录结构

```
HazMatSpider
├── doc
├── spider-admin
│   └── src
│       └── main
│           ├── java
│           │   └── com
│           │       └── spider
│           │           └── web
│           │               ├── controller
│           │               │   ├── common
│           │               │   ├── monitor
│           │               │   ├── system
│           │               │   └── tool
│           │               └── core
│           │                   └── config
│           └── resources
│               ├── i18n
│               ├── META-INF
│               └── mybatis
├── spider-common
│   └── src
│       └── main
│           └── java
│               └── com
│                   └── spider
│                       └── common
│                           ├── annotation
│                           ├── config
│                           │   └── serializer
│                           ├── constant
│                           ├── core
│                           │   ├── controller
│                           │   ├── domain
│                           │   │   ├── entity
│                           │   │   └── model
│                           │   ├── page
│                           │   ├── redis
│                           │   └── text
│                           ├── enums
│                           ├── exception
│                           │   ├── base
│                           │   ├── file
│                           │   ├── job
│                           │   └── user
│                           ├── filter
│                           ├── utils
│                           │   ├── bean
│                           │   ├── file
│                           │   ├── html
│                           │   ├── http
│                           │   ├── ip
│                           │   ├── poi
│                           │   ├── reflect
│                           │   ├── sign
│                           │   ├── spring
│                           │   ├── sql
│                           │   └── uuid
│                           └── xss
├── spider-framework
│   └── src
│       └── main
│           └── java
│               └── com
│                   └── spider
│                       └── framework
│                           ├── aspectj
│                           ├── config
│                           │   └── properties
│                           ├── datasource
│                           ├── interceptor
│                           │   └── impl
│                           ├── manager
│                           │   └── factory
│                           ├── security
│                           │   ├── context
│                           │   ├── filter
│                           │   └── handle
│                           └── web
│                               ├── domain
│                               │   └── server
│                               ├── exception
│                               └── service
├── spider-generator
│   └── src
│       └── main
│           ├── java
│           │   └── com
│           │       └── spider
│           │           └── generator
│           │               ├── config
│           │               ├── controller
│           │               ├── domain
│           │               ├── mapper
│           │               ├── service
│           │               └── util
│           └── resources
│               ├── mapper
│               │   └── generator
│               └── vm
│                   ├── java
│                   ├── js
│                   ├── sql
│                   ├── vue
│                   │   └── v3
│                   └── xml
├── spider-quartz
│   └── src
│       └── main
│           ├── java
│           │   └── com
│           │       └── spider
│           │           └── quartz
│           │               ├── config
│           │               ├── controller
│           │               ├── domain
│           │               ├── enums
│           │               ├── mapper
│           │               ├── service
│           │               │   └── impl
│           │               ├── task
│           │               └── util
│           └── resources
│               └── mapper
│                   └── quartz
├── spider-system
│   └── src
│       └── main
│           ├── java
│           │   └── com
│           │       └── spider
│           │           └── system
│           │               ├── domain
│           │               │   └── vo
│           │               ├── mapper
│           │               └── service
│           │                   └── impl
│           └── resources
│               └── mapper
│                   └── system
├── spider-ui
│   ├── node_modules
│   └── src
│       ├── api
│       │   ├── monitor
│       │   ├── system
│       │   │   └── dict
│       │   └── tool
│       ├── assets
│       │   ├── 401_images
│       │   ├── 404_images
│       │   ├── icons
│       │   │   └── svg
│       │   ├── images
│       │   ├── logo
│       │   └── styles
│       ├── components
│       │   ├── Breadcrumb
│       │   ├── Crontab
│       │   ├── DictData
│       │   ├── DictTag
│       │   ├── Editor
│       │   ├── FileUpload
│       │   ├── Hamburger
│       │   ├── HeaderSearch
│       │   ├── IconSelect
│       │   ├── iFrame
│       │   ├── ImagePreview
│       │   ├── ImageUpload
│       │   ├── Pagination
│       │   ├── PanThumb
│       │   ├── ParentView
│       │   ├── RightToolbar
│       │   ├── RuoYi
│       │   │   ├── Doc
│       │   │   └── Git
│       │   ├── Screenfull
│       │   ├── SizeSelect
│       │   ├── SvgIcon
│       │   ├── ThemePicker
│       │   └── TopNav
│       ├── directive
│       │   ├── dialog
│       │   ├── module
│       │   └── permission
│       ├── layout
│       │   ├── components
│       │   │   ├── Copyright
│       │   │   ├── IframeToggle
│       │   │   ├── InnerLink
│       │   │   ├── Settings
│       │   │   ├── Sidebar
│       │   │   └── TagsView
│       │   └── mixin
│       ├── plugins
│       ├── router
│       ├── store
│       │   └── modules
│       ├── utils
│       │   ├── dict
│       │   └── generator
│       └── views
│           ├── dashboard
│           │   └── mixins
│           ├── error
│           ├── monitor
│           │   ├── cache
│           │   ├── druid
│           │   ├── job
│           │   ├── logininfor
│           │   ├── online
│           │   ├── operlog
│           │   └── server
│           ├── system
│           │   ├── config
│           │   ├── dept
│           │   ├── dict
│           │   ├── menu
│           │   ├── notice
│           │   ├── post
│           │   ├── role
│           │   └── user
│           │       └── profile
│           └── tool
│               ├── gen
│               └── swagger
└── sql
```

## 四、分层架构规范

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

### 接口与实现分离

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

## 五、安全与性能规范

### 输入校验

- 使用 `@Valid` 与 JSR-303 校验注解（如 `@NotBlank`, `@Size` 等）
  - 注意：Spring Boot 2.5.15 中校验注解位于 `jakarta.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`

## 八、通用依赖规则

### 核心依赖

- `spring-boot-starter-web`
- `spring-boot-starter-data-jpa`
- `lombok`
- `druid-spring-boot-starter`
- `kaptcha`
- `oshi-core`
- `spring-boot-starter-security`
- `spring-boot-starter-validation`
- `pagehelper-spring-boot-starter`
- `fastjson2`
- `commons-io`
- `poi-ooxml`
- `springfox-boot-starter`
- `quartz`
- `jsoup`
- `selenium-java`
- `webdrivermanager`
- `playwright`

### 构建工具

- Maven 3.1.1

## 九、编码原则总结

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