# 开发规范指南 为保证代码质量、可维护性、安全性与可扩展性，请在开发过程中严格遵循以下规范。 ## 一、项目基本信息 - **工作目录**：`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 等 |