# standard

**Repository Path**: shisanqian/standard

## Basic Information

- **Project Name**: standard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot 多模块架构(含Admin管理端) 开发规范（落地版）

**适用场景**：SpringBoot + MyBatis 企业级多模块项目
**新增**：`xxx-admin` 管理端独立模块 | **统一返回值**：`AjaxResult`（200成功/400失败）
**完全保留原有规范**，仅新增管理模块、替换返回值，可直接复制为 `README.md`

---

## 一、多模块架构总览（标准企业级 + 独立Admin模块）

### 父工程（项目根目录）

`xxx-project`（打包方式：`pom`，无业务代码，统一管理依赖版本）

### 6 个子模块（职责分离、无循环依赖）

| 模块名         | 核心职责 | 被依赖方 |
| :------------- | :------- | :------- |
| `xxx-common`   | 公共核心：统一返回值、工具类、异常、常量、全局配置 | 所有模块 |
| `xxx-entity`   | 数据模型：所有实体、DTO、VO、入参类（Search/Form） | dao、service、admin |
| `xxx-dao`      | 数据访问：MyBatis Mapper 接口、XML 文件 | service |
| `xxx-service`  | 业务逻辑：Service 接口 + 实现类 | admin |
| `xxx-admin`    | **✅ 新增：后台管理接口模块** | 无（**核心启动模块**） |

---

## 二、模块依赖关系（强制固定）

```
xxx-admin (管理端启动类+Controller，唯一启动模块)
  ↓ 依赖
xxx-service
  ↓ 依赖
xxx-dao + xxx-entity
  ↓ 依赖
xxx-common
```

---

## 三、各模块 内部包结构

### 1. xxx-common（公共模块）

```
com.xxx.common
├── config/        # 全局配置（MyBatis、跨域、线程池等）
├── constant/      # 常量类
├── exception/     # 全局异常处理
├── result/        # ✅ 统一返回值 AjaxResult（核心）
└── util/          # 工具类
```

### 2. xxx-entity（数据模型中心）

```
com.xxx.entity
├── entity/        # 数据库单表实体（DO/PO）
├── dto/           # MyBatis 多表联查结果集
├── vo/            # 接口出参（返回前端）
└── request/       # 接口入参
    ├── search/    # GET ≥3 参数：XxxSearch
    └── form/      # POST 接口：XxxAddForm / XxxUpdateForm
```

### 3. xxx-dao（数据访问层）

```
com.xxx.dao
├── mapper/        # MyBatis Mapper 接口
└── resources/mapper/ # MyBatis XML 文件
```

### 4. xxx-service（业务逻辑层）

```
com.xxx.service
├── UserService.java      # 业务接口
└── impl/
    └── UserServiceImpl.java # 业务实现类
```

### 5. xxx-admin（✅ 新增：后台管理接口模块）

```
com.xxx.admin
├── XxxAdminApplication.java  # 项目唯一启动类
└── controller/               # 所有管理端 GET/POST 接口
    └── UserController.java
```

---

## 四、✅ 统一返回值：AjaxResult（xxx-common）

**状态码规范**：成功=200，失败=400

```java
package com.xxx.common.result;

import lombok.Data;

/**
 * 管理端统一返回结果
 */
@Data
public class AjaxResult<T> {
    private int code;
    private String msg;
    private T data;

    // 1. 成功：无参数
    public static <T> AjaxResult<T> success() {
        AjaxResult<T> result = new AjaxResult<>();
        result.setCode(200);
        result.setMsg("操作成功");
        return result;
    }

    // 2. 成功：自定义消息
    public static <T> AjaxResult<T> success(String msg) {
        AjaxResult<T> result = new AjaxResult<>();
        result.setCode(200);
        result.setMsg(msg);
        return result;
    }

    // 3. 成功：带数据
    public static <T> AjaxResult<T> success(T data) {
        AjaxResult<T> result = new AjaxResult<>();
        result.setCode(200);
        result.setMsg("操作成功");
        result.setData(data);
        return result;
    }

    // 4. 失败：默认消息
    public static <T> AjaxResult<T> fail() {
        AjaxResult<T> result = new AjaxResult<>();
        result.setCode(400);
        result.setMsg("操作失败");
        return result;
    }

    // 5. 失败：自定义消息
    public static <T> AjaxResult<T> fail(String msg) {
        AjaxResult<T> result = new AjaxResult<>();
        result.setCode(400);
        result.setMsg(msg);
        return result;
    }
}
```

---

## 五、核心命名规范（无修改）

| 场景 | 类名规范 | 存放位置 |
| :--- | :------- | :------- |
| GET 参数 ≥3 | UserSearch、OrderSearch | xxx-entity/request/search |
| POST 新增 | UserAddForm | xxx-entity/request/form |
| POST 更新 | UserUpdateForm | xxx-entity/request/form |
| MyBatis 多表联查 | UserOrderDTO | xxx-entity/dto |
| 接口返回前端 | UserVO | xxx-entity/vo |
| 数据库单表实体 | User、Order | xxx-entity/entity |

---

## 六、接口请求规范（强制遵守）

### 1. 全局规则

- 仅允许使用 `GET` / `POST`，**禁用 PUT/DELETE**
- GET 接口**禁止使用 @RequestBody**

### 2. GET 接口

- 参数 < 3：直接用 `@RequestParam` 注解
- 参数 ≥ 3：封装 `XxxSearch` 类
- 数组参数：`List<Long>` / `List<Integer>`

### 3. POST 接口

- 统一 `@RequestBody @Valid XxxForm`
- **新增/更新表单必须分开**

---

## 七、数据类型规范（强制）

### 1. 包装类优先（永远不使用基本类型）

- 主键 ID：`Long`
- 普通数字：`Integer`
- 金额/价格：`BigDecimal`
- 禁止：`int` / `long` / `float` / `double`

### 2. 数据库 NOT NULL 处理

- 无论字段是否非空，**统一用包装类**
- 配合 `@NotNull` / `@NotBlank` 做参数校验

```java
// 正确
private Long id;
private Integer status;
private BigDecimal price;
```

---

## 八、表单验证规范（新增/更新 强制分离）

### 1. UserAddForm（新增）

- 无 ID 字段
- 必传字段加非空校验

### 2. UserUpdateForm（更新）

- 必须包含 `@NotNull Long id`
- 其他字段**选填**，不加非空校验

---

## 九、GET 接口接收数组规范

### 1. 简单场景（参数<3）

```java
@GetMapping("/batch")
public AjaxResult<List<UserVO>> batchGet(@RequestParam List<Long> ids) {}
```

前端传参：`?ids=1,2,3` 或 `?ids=1&ids=2&ids=3`

### 2. 多参数场景（Search 封装）

```java
@Data
public class UserSearch {
    private List<Long> ids; // 无需注解
    private String username;
    private Integer status;
}
```

---

## 十、MyBatis 规范

1. 单表查询 → 返回 `Entity`
2. **多表/三表联查 → 返回 DTO**
3. 结果映射使用 `resultMap`
4. XML 存放：`xxx-dao/resources/mapper/`
5. 禁止在 Entity 中添加联表字段

---

## 十一、标准代码示例（Admin模块 + AjaxResult）

### 1. 启动类（xxx-admin）

```java
package com.xxx.admin;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication(scanBasePackages = "com.xxx")
public class XxxAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(XxxAdminApplication.class, args);
    }
}
```

### 2. GET 接口（<3 参数）

```java
@GetMapping("/detail")
public AjaxResult<UserVO> detail(@RequestParam Long id) {
    UserVO vo = userService.detail(id);
    return AjaxResult.success(vo);
}
```

### 3. GET 接口（≥3 参数，Search）

```java
@GetMapping("/list")
public AjaxResult<List<UserVO>> list(UserSearch search) {
    return AjaxResult.success(userService.list(search));
}
```

### 4. POST 新增接口

```java
@PostMapping("/add")
public AjaxResult<Boolean> add(@RequestBody @Valid UserAddForm form) {
    return AjaxResult.success(userService.add(form));
}
```

### 5. POST 更新接口

```java
@PostMapping("/update")
public AjaxResult<Boolean> update(@RequestBody @Valid UserUpdateForm form) {
    return AjaxResult.success(userService.update(form));
}
```

### 6. 失败返回示例

```java
if (obj == null) {
    return AjaxResult.fail("数据不存在");
}
```