开发规范指南
为保证代码质量、可维护性、安全性与可扩展性，请在开发过程中严格遵循以下规范。
一、项目基本信息
- 工作目录：
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 子包中。
五、安全与性能规范
输入校验
事务管理
@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-webspring-boot-starter-data-jpalombokdruid-spring-boot-starterkaptchaoshi-corespring-boot-starter-securityspring-boot-starter-validationpagehelper-spring-boot-starterfastjson2commons-iopoi-ooxmlspringfox-boot-starterquartzjsoupselenium-javawebdrivermanagerplaywright
构建工具
九、编码原则总结
| 原则 |
说明 |
| SOLID |
高内聚、低耦合，增强可维护性与可扩展性 |
| DRY |
避免重复代码，提高复用性 |
| KISS |
保持代码简洁易懂 |
| YAGNI |
不实现当前不需要的功能 |
| OWASP |
防范常见安全漏洞，如 SQL 注入、XSS 等 |
