# framework

**Repository Path**: huangpengfeiaq/framework

## Basic Information

- **Project Name**: framework
- **Description**: 极力推荐！！基于Spring boot框架搭建的架构模板，一个可直接上手开发的轻量化架构模板。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2021-07-06
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 模板

## README

# 框架说明文档

## 分支说明

- `dev/*`: 开发环境
- `test/*`: 测试环境
- `prod/*`: 生产环境

## 分支版本号说明

- 第一位代表大版本
- 第二位代表小版本
- 第三位代表定制版本

## Controller层场景配置规范

### 外部开放的接口

1. 在`controller`下创建`open`包。
2. 新建类，命名方式为：`XxxOpen`，例如原`ShopController`，则新建`ShopOpen`。
3. 使用注解`@RequestMapping("/open/xxx")`。

示例：
```java
@Slf4j
@RestController
@RequestMapping("/open/product")
@Tag(name = "产品 商品管理")
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)
public class ProductSpuOpen {
    /*
      具体业务
     */
}
```

### 内部使用的接口

#### 不携带token传递

1. 在`controller`下创建`inner`包。
2. 新建类，命名方式为：`XxxInner`，例如原`ShopController`，则新建`ShopInner`。
3. 使用注解`@RequestMapping("/xxx/inner")`。

示例：
```java
@Tag(name = "店铺 店铺管理")
@RestController
@RequestMapping("/shop/inner")
@Slf4j
@Inner
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)
public class ShopControllerInner {
    /*
      具体业务
     */
}
```

远程调用接口示例：
```java
@HttpExchange(value = ServiceNameConstants.BUSINESS_SERVICE + "/shop")
public interface RemoteShopClient {
    @GetExchange("/inner/{id}")
    @NoToken
    R<Shop> innerGetById(@PathVariable("id") Long id);
}
```

#### 携带token传递

1. 在`controller`下创建`inner`包。
2. 新建类，命名方式为：`XxxInner`，例如原`ShopController`，则新建`ShopInner`。
3. 使用注解`@RequestMapping("/xxx/inner")`。

示例：
```java
@Tag(name = "店铺 店铺管理")
@RestController
@RequestMapping("/shop/inner")
@Slf4j
@Inner(noToken = false)
@SecurityRequirement(name = HttpHeaders.AUTHORIZATION)
public class ShopControllerInner {
    /*
      具体业务
     */
}
```

远程调用接口示例：
```java
@HttpExchange(value = ServiceNameConstants.BUSINESS_SERVICE + "/shop")
public interface RemoteShopClient {
    @GetExchange("/inner/{id}")
    @NoToken
    R<Shop> innerGetById(@PathVariable("id") Long id);
}
```

## 代码规范

1. 【强制】远程调用禁止返回list对象集合。
2. 【强制】禁止嵌套for循环。
3. 【强制】禁止在service层引入非本类的dao层代码。
4. 【强制】禁止在service层返回R对象。如需异常终止，请使用`throw new BizException();`。
5. 【强制】禁止滥用VO、DTO、VO、DTO等对象。
    - `xxxDTO`仅可作为方法参数，禁止DTO对象作为方法返回。
    - `xxxVO`仅作为方法返回对象，禁止VO对象作为参数传递。
6. 【强制】service层方法命名规则
    - 查询集合必须用`listBy`开头
    - 查询单个必须用`getBy`开头
    - 查询统计必须用`countBy`开头
    - 查询存在必须用`existsBy`开头
    - 修改必须用`updateBy`开头
    - 删除必须用`deleteBy`开头
    - 新增必须用`saveBy`开头
7. 【强制】禁止在任何地方出现warning代码，禁止使用`@SuppressWarnings`抑制警告，除了个别框架自身缺陷所导致的警告。
8. 【强制】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。可复用常量需使用枚举类抽取，使用时引入。
9. 【强制】提交之前格式化，删除无用引用，去除未使用变量；专有名词大写，静态变量大写snake。
10. 【强制】潜在的通用方法需要抽取为内部private方法，禁止在同个类内复制类似代码。
11. 【强制】前后端交互的 API，原则上遵循restful风格。
    - 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：
        - 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。
        - URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。
        - 路径禁止携带表示请求内容类型的后缀，比如".json"，".xml"，通过 accept 头表达即可。
    - 请求方法：对具体操作的定义，常见的请求方法如下：
        - GET：从服务器取出资源。
        - POST：在服务器新建一个资源。
        - PUT：在服务器更新资源。
        - DELETE：从服务器删除资源。
12. 【建议】单个方法原则上小于40行，最大不超过80行。
13. 【建议】尽量使用链式表达式替代创建局部变量，尽量使用三目运算符替代if-else，尽量使用循环代替递归。简化代码，提高可读性。
14. 【建议】通用逻辑尽量采用声明式替代编程式。依据业务显示或隐示的添加必要注释信息。

## 注释规范

1. 【强制】除`serviceImpl`包下的方法外，所有方法必须含有标准的javadoc注释，即功能描述，形参及返回值。
2. 【建议】业务方法内他人无法直接理解的代码，以及关键代码，按需给予单行注释。
3. 【强制】对于过时的方法，必须标识`@Deprecated`，并说明过时版本及迁移方案。

## 设计规范

1. 【强制】严格按照DDD领域驱动设计规范进行设计及命名规范。有助于减少沟通误解，使代码更能体现业务含义。
2. 【强制】禁止滥用DO / PO / DTO / BO / VO命名。
3. 【强制】Mapper层禁止使用xml作为数据映射，避免一些无法把控的错误，如必要可使用注解方式替代。

## 小技巧

1. 【建议】使用`BeanUtils.copyProperties()`方法代替`setXxx()`&`getXxx()`的属性拷贝。