122 lines
3.5 KiB
Markdown
122 lines
3.5 KiB
Markdown
# API 参数变更通知模版
|
||
|
||
对应 `11.py` → `build_markdown_notification()` 中参数变更分支 + `_format_endpoint_block()`。
|
||
适用：**URI 与 HTTP 方法均未变**，仅入参发生变化。
|
||
|
||
---
|
||
|
||
## 完整示例
|
||
|
||
```
|
||
# 【API参数变更通知】
|
||
- **修改人：** dongzi
|
||
- **修改时间：** 2026-06-08 16:30:00
|
||
|
||
- **变更类型：** <font color="warning">**修改参数**</font>
|
||
- **URI：** **POST** `/apply/clockIn`
|
||
- **路径：** <font color="info">**jnpf-ftb/jnpf-ftb-biz/src/main/java/jnpf/workflow/controller/ApplyClockInController.java**</font>
|
||
|
||
---------------------------------------
|
||
|
||
#### 【接口参数变动详情】
|
||
|
||
**类对象变更（一级字段）**
|
||
|
||
共 **1** 个类对象 · **2** 项字段变更
|
||
|
||
**`ApplyAttendanceChangeDto`**
|
||
|
||
├─ `taskIds` · `List<String>` · 必填 [新增]
|
||
> 说明：流程主键集合
|
||
└─ `applyUser1` · `Integer` [删除]
|
||
> 说明：申请人员
|
||
|
||
**普通参数变更**
|
||
|
||
共 **1** 项变更
|
||
|
||
1. `id` · `String` · 路径参数 [新增]
|
||
> 说明：主键
|
||
```
|
||
|
||
---
|
||
|
||
## 示例（仅普通参数，无 RequestBody）
|
||
|
||
```
|
||
# 【API参数变更通知】
|
||
- **修改人：** dongzi
|
||
- **修改时间：** 2026-06-08 16:30:00
|
||
|
||
- **变更类型：** <font color="warning">**修改参数**</font>
|
||
- **URI：** **GET** `/apply/clockIn/{id}`
|
||
- **路径：** <font color="info">**jnpf-ftb/.../ApplyClockInController.java**</font>
|
||
|
||
---------------------------------------
|
||
|
||
#### 【接口参数变动详情】
|
||
|
||
**普通参数变更**
|
||
|
||
共 **1** 项变更
|
||
|
||
1. `pageSize` · `Integer` · 查询参数 [新增]
|
||
```
|
||
|
||
---
|
||
|
||
## 参数分类与检测
|
||
|
||
| 来源注解 | `source` 字段 | diff 粒度 |
|
||
|----------|---------------|-----------|
|
||
| `@RequestBody` | `body` | Dto **一级字段**（复用 `FieldDiffEngine`） |
|
||
| `@PathVariable` | `path` | 参数名、类型、增删 |
|
||
| `@RequestParam` | `query` | 参数名、类型、required、增删 |
|
||
| 无注解 | `simple` | 待确认是否纳入 |
|
||
|
||
### 排除的框架参数（建议默认开启）
|
||
|
||
`HttpServletRequest`、`HttpServletResponse`、`BindingResult`、`Principal`、`Authentication`、`Model`、`ModelMap`、`UriComponentsBuilder` 等。
|
||
|
||
---
|
||
|
||
## ParameterChange 数据结构（对齐 11.py）
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `param_name` | 当前参数名 / 字段名 |
|
||
| `old_name` | 重命名前名称 |
|
||
| `param_type` | 类型字符串，如 `List<String>` |
|
||
| `description` | 说明（@Schema / 注释） |
|
||
| `source` | `body` / `path` / `query` |
|
||
| `body_param_name` | `@RequestBody` 形参名 |
|
||
| `parent_dto` | Dto 简单类名 |
|
||
| `change_type` | `added` / `removed` / `modified` / `renamed` |
|
||
| `detail` | 类型变化等详情 |
|
||
|
||
---
|
||
|
||
## 与路径变更的拆分规则（11.py 约定）
|
||
|
||
| 同一次改动 | 通知策略 |
|
||
|------------|----------|
|
||
| 仅参数变 | 本模版 |
|
||
| 路径变 + 参数变 | **拆两条**：先路径通知，再参数通知 |
|
||
| 方法变 + 参数变 | **拆两条**：先方法通知，再参数通知 |
|
||
| 新增接口 + 带参数 | 路径通知可**附带**参数详情区块 |
|
||
|
||
---
|
||
|
||
## JavaParser 实现要点
|
||
|
||
1. **EndpointSnapshotParser**：遍历 `MethodDeclaration.getParameters()`，读参数注解
|
||
2. **@RequestBody**：取 Dto 类型 → `ClassFieldParser.parseFields()` 得字段列表
|
||
3. **ParameterDiffEngine**：旧/新快照按方法指纹对齐后 diff
|
||
4. **ApiChangeNotifier**：渲染本模版；泛型类型展示规则与类变更通知一致（`<>` 不 HTML 转义）
|
||
|
||
## 实现
|
||
|
||
- `ParameterDiffEngine`
|
||
- `ApiChangeNotifier.formatEndpointBlock()`
|
||
- 复用 `FieldDiffEngine` / `WeComNotifier` 中的字段行格式（可选统一）
|