395 lines
11 KiB
Markdown
395 lines
11 KiB
Markdown
# API 文档 - 代码覆盖率功能
|
||
|
||
## 元数据
|
||
- 需求编号：002-04
|
||
- 需求名称：代码覆盖率
|
||
- 创建时间：2026-02-05
|
||
- 创建人：AI Assistant
|
||
- 版本：v2.0.0
|
||
- 状态：已完成
|
||
|
||
## API 概述
|
||
代码覆盖率功能 API 提供了 Salesforce Apex 代码覆盖率的查询、统计和分析能力。通过这组 API，用户可以：
|
||
- 分页查询代码覆盖率列表，支持多条件筛选
|
||
- 查询单个代码覆盖率记录的详细信息
|
||
- 获取指定测试结果的总体代码覆盖率统计
|
||
- 按类型（Class/Trigger）统计代码覆盖率
|
||
|
||
所有 API 均遵循 RESTful 设计规范，返回统一的结果格式（ResultVo），支持权限控制（独立权限标识 `apex:coverage:query`）。
|
||
|
||
## 接口列表
|
||
|
||
### 接口 1：查询代码覆盖率列表
|
||
|
||
#### 功能描述
|
||
分页查询代码覆盖率列表，支持按测试结果 ID、类/触发器名称、类型、命名空间、覆盖率范围等多条件筛选。
|
||
|
||
#### 请求方式
|
||
POST
|
||
|
||
#### 请求路径
|
||
`/api/salesforce/apex/coverage/list`
|
||
|
||
#### 权限标识
|
||
`apex:coverage:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| testResultId | Long | 是 | 测试结果 ID，关联 datai_apex_test_result 表 |
|
||
| name | String | 否 | 类/触发器名称，支持模糊查询，长度 1-255 字符 |
|
||
| type | String | 否 | 类型，可选值：Class、Trigger |
|
||
| namespace | String | 否 | 命名空间，支持模糊查询，长度 1-255 字符 |
|
||
| minCoverage | Double | 否 | 最小覆盖率（0.0-100.0） |
|
||
| maxCoverage | Double | 否 | 最大覆盖率（0.0-100.0） |
|
||
| pageNum | Integer | 否 | 页码，默认 1，最小 1 |
|
||
| pageSize | Integer | 否 | 每页大小，默认 10，范围 1-100 |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 分页结果数据 |
|
||
| data.total | Long | 总记录数 |
|
||
| data.rows | Array | 代码覆盖率记录列表 |
|
||
| data.rows[].id | Long | 记录 ID |
|
||
| data.rows[].testResultId | Long | 测试结果 ID |
|
||
| data.rows[].name | String | 类/触发器名称 |
|
||
| data.rows[].type | String | 类型（Class/Trigger） |
|
||
| data.rows[].namespace | String | 命名空间 |
|
||
| data.rows[].numLocations | Integer | 总代码行数 |
|
||
| data.rows[].numLocationsNotCovered | Integer | 未覆盖代码行数 |
|
||
| data.rows[].coveragePercent | Double | 覆盖率百分比（0.00-100.00） |
|
||
|
||
#### 成功示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"total": 15,
|
||
"rows": [
|
||
{
|
||
"id": 1,
|
||
"testResultId": 100,
|
||
"name": "AccountController",
|
||
"type": "Class",
|
||
"namespace": "MyNamespace",
|
||
"numLocations": 100,
|
||
"numLocationsNotCovered": 20,
|
||
"coveragePercent": 80.00
|
||
},
|
||
{
|
||
"id": 2,
|
||
"testResultId": 100,
|
||
"name": "ContactTrigger",
|
||
"type": "Trigger",
|
||
"namespace": "MyNamespace",
|
||
"numLocations": 50,
|
||
"numLocationsNotCovered": 5,
|
||
"coveragePercent": 90.00
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "testResultId 不能为空"
|
||
}
|
||
```
|
||
|
||
#### 错误码
|
||
- 200：操作成功
|
||
- 500：服务器内部错误（testResultId 不能为空、参数验证失败等）
|
||
|
||
---
|
||
|
||
### 接口 2：查询代码覆盖率详情
|
||
|
||
#### 功能描述
|
||
根据 ID 查询单个代码覆盖率记录的详细信息。
|
||
|
||
#### 请求方式
|
||
GET
|
||
|
||
#### 请求路径
|
||
`/api/salesforce/apex/coverage/{id}`
|
||
|
||
#### 权限标识
|
||
`apex:coverage:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 代码覆盖率记录 ID，路径参数，最小 1 |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 代码覆盖率详情数据 |
|
||
| data.id | Long | 记录 ID |
|
||
| data.testResultId | Long | 测试结果 ID |
|
||
| data.name | String | 类/触发器名称 |
|
||
| data.type | String | 类型（Class/Trigger） |
|
||
| data.namespace | String | 命名空间 |
|
||
| data.numLocations | Integer | 总代码行数 |
|
||
| data.numLocationsNotCovered | Integer | 未覆盖代码行数 |
|
||
| data.coveragePercent | Double | 覆盖率百分比（0.00-100.00） |
|
||
|
||
#### 成功示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"testResultId": 100,
|
||
"name": "AccountController",
|
||
"type": "Class",
|
||
"namespace": "MyNamespace",
|
||
"numLocations": 100,
|
||
"numLocationsNotCovered": 20,
|
||
"coveragePercent": 80.00
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "代码覆盖率记录不存在"
|
||
}
|
||
```
|
||
|
||
#### 错误码
|
||
- 200：操作成功
|
||
- 500：服务器内部错误（代码覆盖率记录不存在、参数验证失败等）
|
||
|
||
---
|
||
|
||
### 接口 3：查询总体代码覆盖率统计
|
||
|
||
#### 功能描述
|
||
统计指定测试结果的总体代码覆盖率，包括加权平均覆盖率、总代码行数、未覆盖代码行数、已覆盖代码行数。
|
||
|
||
#### 请求方式
|
||
POST
|
||
|
||
#### 请求路径
|
||
`/api/salesforce/apex/coverage/summary`
|
||
|
||
#### 权限标识
|
||
`apex:coverage:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| testResultId | Long | 是 | 测试结果 ID，关联 datai_apex_test_result 表 |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 覆盖率统计数据 |
|
||
| data.testResultId | Long | 测试结果 ID |
|
||
| data.totalClasses | Integer | 总类/触发器数量 |
|
||
| data.totalLines | Integer | 总代码行数 |
|
||
| data.coveredLines | Integer | 已覆盖代码行数 |
|
||
| data.uncoveredLines | Integer | 未覆盖代码行数 |
|
||
| data.averageCoverage | Double | 加权平均覆盖率百分比（0.00-100.00） |
|
||
|
||
#### 成功示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"testResultId": 100,
|
||
"totalClasses": 15,
|
||
"totalLines": 1500,
|
||
"coveredLines": 1200,
|
||
"uncoveredLines": 300,
|
||
"averageCoverage": 80.00
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "testResultId 不能为空"
|
||
}
|
||
```
|
||
|
||
#### 错误码
|
||
- 200：操作成功
|
||
- 500：服务器内部错误（testResultId 不能为空、参数验证失败等）
|
||
|
||
---
|
||
|
||
### 接口 4：按类型统计代码覆盖率
|
||
|
||
#### 功能描述
|
||
按类型（Class/Trigger）统计代码覆盖率，返回每种类型的覆盖率统计信息。
|
||
|
||
#### 请求方式
|
||
POST
|
||
|
||
#### 请求路径
|
||
`/api/salesforce/apex/coverage/summary-by-type`
|
||
|
||
#### 权限标识
|
||
`apex:coverage:query`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| testResultId | Long | 是 | 测试结果 ID，关联 datai_apex_test_result 表 |
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 按类型统计的覆盖率数据 |
|
||
| data.testResultId | Long | 测试结果 ID |
|
||
| data.typeSummaries | Array | 类型统计列表 |
|
||
| data.typeSummaries[].type | String | 类型（Class/Trigger） |
|
||
| data.typeSummaries[].totalClasses | Integer | 该类型的类/触发器数量 |
|
||
| data.typeSummaries[].totalLines | Integer | 该类型的总代码行数 |
|
||
| data.typeSummaries[].coveredLines | Integer | 该类型的已覆盖代码行数 |
|
||
| data.typeSummaries[].uncoveredLines | Integer | 该类型的未覆盖代码行数 |
|
||
| data.typeSummaries[].averageCoverage | Double | 该类型的加权平均覆盖率百分比（0.00-100.00） |
|
||
|
||
#### 成功示例
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"testResultId": 100,
|
||
"typeSummaries": [
|
||
{
|
||
"type": "Class",
|
||
"totalClasses": 10,
|
||
"totalLines": 1000,
|
||
"coveredLines": 850,
|
||
"uncoveredLines": 150,
|
||
"averageCoverage": 85.00
|
||
},
|
||
{
|
||
"type": "Trigger",
|
||
"totalClasses": 5,
|
||
"totalLines": 500,
|
||
"coveredLines": 350,
|
||
"uncoveredLines": 150,
|
||
"averageCoverage": 70.00
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败示例
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "testResultId 不能为空"
|
||
}
|
||
```
|
||
|
||
#### 错误码
|
||
- 200：操作成功
|
||
- 500：服务器内部错误（testResultId 不能为空、参数验证失败等）
|
||
|
||
## 错误码
|
||
|
||
### 通用错误码
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 200 | 操作成功 | 无需处理 |
|
||
| 401 | 未授权 | 检查用户是否登录，Token 是否有效 |
|
||
| 403 | 权限不足 | 检查用户是否具有 `apex:coverage:query` 权限 |
|
||
| 404 | 资源不存在 | 检查请求路径是否正确 |
|
||
| 500 | 服务器内部错误 | 查看服务器日志，排查具体错误原因 |
|
||
|
||
### 业务错误码
|
||
| 错误码 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| 500 | testResultId 不能为空 | 确保请求参数中包含 testResultId |
|
||
| 500 | 代码覆盖率记录不存在 | 检查 id 参数是否正确，记录是否已删除 |
|
||
| 500 | 参数验证失败 | 检查请求参数是否符合要求（如类型、范围等） |
|
||
|
||
## 数据模型
|
||
|
||
### QueryCodeCoverageDto（查询代码覆盖率请求）
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| testResultId | Long | 测试结果 ID |
|
||
| name | String | 类/触发器名称 |
|
||
| type | String | 类型（Class/Trigger） |
|
||
| namespace | String | 命名空间 |
|
||
| minCoverage | Double | 最小覆盖率 |
|
||
| maxCoverage | Double | 最大覆盖率 |
|
||
| pageNum | Integer | 页码 |
|
||
| pageSize | Integer | 每页大小 |
|
||
|
||
### CodeCoverageResultVo（代码覆盖率结果）
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 记录 ID |
|
||
| testResultId | Long | 测试结果 ID |
|
||
| name | String | 类/触发器名称 |
|
||
| type | String | 类型（Class/Trigger） |
|
||
| namespace | String | 命名空间 |
|
||
| numLocations | Integer | 总代码行数 |
|
||
| numLocationsNotCovered | Integer | 未覆盖代码行数 |
|
||
| coveragePercent | Double | 覆盖率百分比 |
|
||
|
||
### CodeCoverageSummaryVo（代码覆盖率统计）
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| testResultId | Long | 测试结果 ID |
|
||
| totalClasses | Integer | 总类/触发器数量 |
|
||
| totalLines | Integer | 总代码行数 |
|
||
| coveredLines | Integer | 已覆盖代码行数 |
|
||
| uncoveredLines | Integer | 未覆盖代码行数 |
|
||
| averageCoverage | Double | 加权平均覆盖率 |
|
||
|
||
### CoverageTypeSummaryVo（按类型统计）
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| type | String | 类型（Class/Trigger） |
|
||
| totalClasses | Integer | 该类型的类/触发器数量 |
|
||
| totalLines | Integer | 该类型的总代码行数 |
|
||
| coveredLines | Integer | 该类型的已覆盖代码行数 |
|
||
| uncoveredLines | Integer | 该类型的未覆盖代码行数 |
|
||
| averageCoverage | Double | 该类型的加权平均覆盖率 |
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-002-04-代码覆盖率.md)
|
||
- [设计文档](../design/2026-02-03-002-04-代码覆盖率-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-002-04-ADR-代码覆盖率技术选型.md)
|
||
- [提示词文档](../prompts/2026-02-05-002-04-prompt-代码覆盖率.md)
|
||
- [会话记录](../sessions/2026-02-05-002-04-session.md)
|
||
- [变更日志 v2.0.0](../changelog/2026-02-05-002-04-changelog-v2.md)
|
||
- [复盘文档](../retros/2026-02-05-002-04-retro.md)
|