CloudBot - 微服务平台

Appearance

📏 技术规范 ​

💾 数据库规范 ​

🛠️ 开发规范 ​

📦 后端规范 ​

项目命名规范 ​

  • 全部采用小写方式， 以中划线分隔。

包名命名规范 ​

  • 小写字母：包名应由小写字母组成，避免使用大写字母。
  • 避免使用保留字：不要使用Java的关键字或保留字作为包名。
  • 遵循反域名命名：通常采用反向域名命名规则，例如：com.companyname.projectname。

分层命名规范 ​

1. 分层结构规范 ​

层级包名规范说明类命名后缀
Controller 层.controller处理 HTTP 请求和响应Controller
Service 层.service
.service.impl		业务逻辑层，接口与实现分离接口：Service
实现类：ServiceImpl
Mapper / DAO 层.mapper (推荐)
或 .dao		数据库操作层（MyBatis 推荐用 mapper）接口：Mapper 或 Dao
Entity / DO 层.entity 或 .domain数据库表映射实体类Entity 或 DO（Data Object）
DTO 层.dto数据传输对象（Controller 入参/出参）DTO
VO 层.vo视图对象（前端展示模型）VO
Util 工具类.utils通用工具类Utils

2. 包结构示例 ​

lua
com
└── company
    └── project
        ├── controller  # 控制层
        ├── service     # 服务接口
        ├── impl        # 服务实现（包）
        ├── mapper      # 数据访问层
        ├── entity      # 实体类
        ├── dto         # 数据传输对象
        ├── vo          # 视图对象
        └── utils       # 工具类

代码目录结构规范 ​

模块命名 ​

  • 模块命名清晰：模块名称应能清晰地表示该模块的功能。例如：user-management 或 order-service。

类名和接口名 ​

  • 大驼峰命名法（Pascal Case）：类名和接口名的每个单词的首字母都应该大写。例如：StudentManager。
  • 避免使用下划线：类名和接口名中不应该使用下划线 _。
  • 接口命名：接口名应该尽量使用形容词或以 able 或 ible 结尾的词来表示能力，例如 Readable、Serializable。

方法参数规范 ​

变量名 ​

  • 小驼峰命名法：变量名应使用小写字母开头，后续单词首字母大写。例如：totalAmount。
  • 具有意义：变量名应具有清晰的含义，避免使用无意义的名称如 a, b 等。
  • 常量命名：常量名应该使用全大写字母，单词之间用下划线分隔。例如：MAX_COUNT。

接口文档规范 ​

  • 项目中生成接口文档时，采用 SpringDoc，默认优先通过规范的注释来描述接口信息，其次才使用注解。

Controller 层规范 ​

在 Spring Boot 项目中，Controller 层的设计和规范化非常重要，能够提升代码的可维护性、可读性和扩展性。以下是一些常见的 Controller 层规范和设计建议：

1. Controller 层命名规范 ​

  • 类名：Controller 类的命名应清晰明了，并且通常以“Controller”结尾。例如：UserController、OrderController 等。
  • 方法名：Controller 中的方法应具备语义化，方法名通常表示该接口所执行的操作，例如：createUser()、updateOrder()、getUserById()。

2. 请求映射注解规范 ​

  • 类级别映射：使用 @RequestMapping 或其子注解（如 @GetMapping、@PostMapping 等）在类上指定请求路径。
    java
    @RestController
@RequestMapping("/users")
public class UserController {
    // 方法
}
  • 方法级别映射：在方法上添加具体的请求路径和方法类型。例如：
    java
    @GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
    // 获取用户信息
}

@PostMapping
public User createUser(@RequestBody User user) {
    // 创建用户
}

3. 统一返回格式 ​

  • 推荐使用统一的响应封装类来规范 API 的返回格式。例如：
    java
    public class ApiResponse<T> {
    private int status;
    private String message;
    private T data;

    // 构造函数、getter 和 setter
}
  • 在 Controller 层中，返回统一格式的响应：
    java
    @GetMapping("/{id}")
public ApiResponse<User> getUser(@PathVariable Long id) {
    User user = userService.getUserById(id);
    return new ApiResponse<>(200, "Success", user);
}

4. 输入验证和异常处理 ​

  • 输入验证：利用 @Valid 或 @Validated 注解进行参数验证，结合 @RequestBody、@RequestParam 等注解。
    java
    @PostMapping
public ApiResponse<User> createUser(@RequestBody @Valid User user) {
    // 创建用户
}
  • 异常处理：使用 @ExceptionHandler 或全局异常处理机制（@ControllerAdvice）来处理异常，保持代码简洁。
    java
    @ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiResponse<String>> handleNotFoundException(ResourceNotFoundException ex) {
        ApiResponse<String> response = new ApiResponse<>(404, ex.getMessage(), null);
        return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
    }
}

5. RESTful API 设计 ​

  • 遵循 RESTful 风格：确保 URL 和 HTTP 方法符合 RESTful 风格。
    • GET：获取资源，例如：/users/{id}
    • POST：创建新资源，例如：/users
    • PUT：更新资源，例如：/users/{id}
    • DELETE：删除资源，例如：/users/{id}

6. 避免逻辑过多 ​

  • Controller 层应仅负责处理 HTTP 请求、调用业务层（Service）并返回响应，不应包含业务逻辑。业务逻辑应放在 Service 层。

7. 注解使用规范 ​

  • 使用合适的注解来区分方法的 HTTP 请求类型，如 @GetMapping、@PostMapping、@PutMapping 和 @DeleteMapping。
  • 控制器方法中的路径变量和请求参数应清晰定义并尽量避免过多的参数，避免使用复杂的路径结构。

8. 版本控制 ​

  • 如果 API 会有版本更新，可以在 URL 中加上版本号，常见方式有：
    java
    @RequestMapping("/v1/users")
public class UserController {
    // 方法
}

9. 日志记录 ​

  • 在 Controller 层记录重要操作的日志，如请求路径、参数、响应等，方便调试和追踪。

10. 请求体和响应体的处理 ​

  • 确保请求和响应的格式清晰，采用统一的格式进行处理，支持常见的请求格式，如 JSON、XML 等。
  • 使用 @RequestBody 接收请求体，使用 @ResponseBody 或 @RestController 自动处理响应。

通过以上的规范，Controller 层的代码将更加简洁、可维护，并且能够确保 API 设计的一致性和标准化。

Service 层规范 ​

4. 方法命名规范（手册要求） ​

操作类型Service / Mapper 方法前缀示例
新增save / insertsaveUser(UserDO user)
删除remove / deleteremoveById(Long id)
修改updateupdateUser(UserDO user)
查询（单个）get / selectgetUserById(Long id)
查询（列表）listlistUsers()
统计countcountUsers()

DAO 层规范 ​

4. 方法命名规范（手册要求） ​

操作类型Service / Mapper 方法前缀示例
新增save / insertsaveUser(UserDO user)
删除remove / deleteremoveById(Long id)
修改updateupdateUser(UserDO user)
查询（单个）get / selectgetUserById(Long id)
查询（列表）listlistUsers()
统计countcountUsers()

Java Bean 规范 ​

《阿里巴巴 Java 开发手册》

领域模型命名规约

  • 1） 数据对象：xxxDO，xxx 即为数据表名。
  • 2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
  • 3） 展示对象：xxxVO，xxx 一般为网页名称。
  • 4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

Boolean 类型属性命名规范 ​

在 Spring Boot 项目中，boolean 类型属性（字段）的命名需遵循 JavaBean 规范和行业最佳实践，以确保与框架机制（如 Dubbo 序列化、Jackson 序列化、Thymeleaf 模板、ConfigurationProperties 绑定等）正确交互。以下是核心规范和建议：

字段命名规范（重点） ​

  • 禁止以 is 开头
    ❌ 错误示例：private boolean isActive;
    ✅ 正确示例：private boolean actived;
  • 使用形容词或状态描述
    如 enabled, visibled, verified，直接表达状态含义。
  • 避免否定式命名
    ❌ 不推荐：isNotReady（易引发逻辑混乱）

阿里巴巴 Java 开发手册

POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。

反例：定义为基本数据类型 Boolean isDeleted；的属性，它的方法也是 isDeleted()，RPC 框架在反向解析的时候，“以为”对应的属性名称是 deleted，导致属性获取不到，进而抛出异常。

关键总结：字段名永远不要用 is 开头，Getter 坚持用 isXxx()，Setter 坚持用 setXxx()。这能避免 Spring Boot 生态中 99% 的兼容性问题。

🎨 UI 设计规范 ​

🖥️ 前端规范 ​

Web 端 ​

  • Web 端 使用 Ant Design 的 Vue 实现，开发和服务于企业级后台产品。

Ant Design Vue 特性 ​

  • 提炼自企业级中后台产品的交互语言和视觉风格。
  • 开箱即用的高质量 Vue 组件。
  • 共享Ant Design of React 设计工具体系。

Web 中后台管理系统 ​

  • Web 中后台管理系统 采用 Vben Admin 2.x 与 Vben Admin 5.x

H5、小程序、APP 移动端 ​

  • 采用 uni-app 及 uni-app x。

🔗 接口规范 ​

💻 代码规范 ​