跳到主要内容

API测试

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-cloud 项目的 API 测试实践，覆盖以下主题：

  • RESTful API 测试基础：HTTP 方法、URL 构造、请求头、请求体格式
  • Postman 集合与环境：集合创建、环境变量、预请求脚本与测试脚本
  • RestAssured 在 Java 项目中的应用：DSL 语法、请求构建、响应断言
  • Swagger UI 在线调试：接口浏览、参数校验、响应查看
  • 最佳实践：参数校验、状态码检查、响应时间监控、错误处理测试
  • 具体用例示例：系统管理、设备管理、黑名单管理等模块
  • 自动化测试与持续集成：Jenkins/ GitHub Actions 流程

项目结构​

围绕 API 测试的关键位置与文件：

  • Postman/IDE 环境变量：script/idea/http-client.env.json
  • Swagger 文档配置：yudao-framework/yudao-spring-boot-starter-web 下的 Swagger 自动配置与属性类
  • 单元测试基类：yudao-framework/yudao-spring-boot-starter-test 提供的 BaseDbUnitTest、BaseMockitoUnitTest
  • 文档化接口：docs/system、docs/device、docs/blacklist 等模块文档
  • CI/CD：.github/workflows/maven.yml、deploy/jenkins/prod/web-build-deploy.Jenkinsfile.sh

Mermaid Diagram Code:

graph TB
subgraph "测试与文档"
ENV["环境变量<br/>script/idea/http-client.env.json"]
SWAGGER_CFG["Swagger配置<br/>YudaoSwaggerAutoConfiguration.java"]
SWAGGER_PROP["Swagger属性<br/>SwaggerProperties.java"]
DOCS_SYS["系统模块文档<br/>docs/system/*.md"]
DOCS_DEV["设备模块文档<br/>docs/device/*.md"]
DOCS_BLK["黑名单模块文档<br/>docs/blacklist/*.md"]
end
subgraph "测试基类"
BASE_DB["BaseDbUnitTest.java"]
BASE_MOCK["BaseMockitoUnitTest.java"]
end
subgraph "CI/CD"
GHA["GitHub Actions<br/>.github/workflows/maven.yml"]
JENKINS["Jenkins 发布脚本<br/>web-build-deploy.Jenkinsfile.sh"]
end
ENV --> SWAGGER_CFG
SWAGGER_CFG --> SWAGGER_PROP
DOCS_SYS --> ENV
DOCS_DEV --> ENV
DOCS_BLK --> ENV
BASE_DB --> ENV
BASE_MOCK --> ENV
GHA --> JENKINS

图表来源

章节来源

核心组件​

  • 环境变量与基础 URL
    • 本地与网关环境分别提供 admin-api 与 app-api 的基础 URL、token、租户 ID 等，便于统一切换测试环境。
  • Swagger 文档与配置
    • 自动装配 OpenAPI，支持全局安全方案与信息配置；通过属性类集中管理标题、描述、版本、许可等。
  • 单元测试基类
    • BaseDbUnitTest：引入内存数据库、MyBatis、SQL 清理等，适合集成测试场景。
    • BaseMockitoUnitTest：纯 Mockito 扩展，适合隔离单元测试。
  • CI/CD 流程
    • GitHub Actions：多 JDK 版本构建。
    • Jenkins：模块化构建与部署脚本。

章节来源

架构总览​

下图展示 API 测试在 yudao-cloud 中的总体关系：环境变量驱动请求构建，Swagger 提供接口文档与在线调试入口，单元测试基类支撑后端验证，CI/CD 确保自动化与可重复性。

Mermaid Diagram Code:

graph TB
ENV["环境变量<br/>http-client.env.json"]
POSTMAN["Postman 集合"]
IDE_HTTP["IDE HTTP Client"]
SWAGGER["Swagger UI"]
TEST_BASE["测试基类<br/>BaseDbUnitTest / BaseMockitoUnitTest"]
CI["CI/CD<br/>GitHub Actions / Jenkins"]
ENV --> POSTMAN
ENV --> IDE_HTTP
POSTMAN --> SWAGGER
IDE_HTTP --> SWAGGER
TEST_BASE --> SWAGGER
CI --> POSTMAN
CI --> IDE_HTTP

图表来源

详细组件分析​

Postman 集合与环境变量​

  • 环境变量
    • 提供 baseUrl、systemBaseUrl、infaBaseUrl、appApi、token、adminTenantId、tag、appToken、appTenentId 等键值，便于在不同环境间切换。
  • 集合创建
    • 建议按模块划分集合（如系统管理、设备管理、黑名单管理），每个集合包含认证、查询、新增、修改、删除等典型场景。
  • 预请求脚本
    • 用于动态注入 token、tenantId、时间戳、签名等。
  • 测试脚本
    • 断言状态码、响应结构字段、业务状态码、错误消息等。

章节来源

RestAssured 在 Java 项目中的应用​

  • DSL 语法与请求构建
    • 使用 given().spec() 统一配置 baseUrl、headers、cookies、auth 等。
    • 使用 pathParam、queryParam、formParams、body 等组织请求参数。
  • 响应验证
    • 使用 statusCode、extract()、jsonPath()、assertThat() 进行断言。
  • 与测试基类结合
    • 在 BaseDbUnitTest 环境中，可直接访问业务层与数据库，进行更完整的集成测试。

章节来源

Swagger UI 在线调试​

  • 启用与配置
    • 通过 YudaoSwaggerAutoConfiguration 自动装配 OpenAPI，并在属性类中配置标题、描述、版本、许可等。
  • 在线调试
    • 在浏览器打开 Swagger UI，选择对应接口，填写参数，点击“Try it out”，查看请求与响应。
  • 参数校验
    • 结合注解与属性校验，确保必填项、格式、范围等符合要求。
  • 响应查看
    • 查看响应状态码、响应头、响应体结构与示例。

章节来源

API 测试最佳实践​

  • 参数验证
    • 必填字段、类型、长度、范围、格式校验；边界值与异常值测试。
  • 状态码检查
    • 成功、未授权、禁止、参数错误、业务错误、服务器错误等。
  • 响应时间监控
    • 在 CI/CD 中记录关键接口耗时，建立阈值告警。
  • 错误处理测试
    • 模拟网络异常、鉴权失败、业务异常、并发冲突等场景。
  • 数据一致性
    • 对写操作进行读取验证，确保数据库状态与接口返回一致。

具体 API 测试用例（示例）​

系统管理（用户管理）​

  • 场景：用户列表查询
    • 方法：GET
    • 路径：/system/user/list
    • 请求头：Authorization: Bearer {token}, tenant-id: {adminTenantId}
    • 查询参数：pageNo、pageSize、status、beginTime、endTime
    • 断言：状态码 200、total 正数、列表字段完整
  • 场景：新增用户
    • 方法：POST
    • 路径：/system/user/create
    • 请求头：Authorization: Bearer {token}, Content-Type: application/json
    • 请求体：用户名、手机号、部门、角色等
    • 断言：状态码 200、返回主键非空、数据库存在该用户
  • 场景：更新用户
    • 方法：POST
    • 路径：/system/user/update
    • 请求体：id、昵称、头像等
    • 断言：状态码 200、更新成功
  • 场景：删除用户
    • 方法：POST
    • 路径：/system/user/delete
    • 请求体：id
    • 断言：状态码 200、数据库不存在该用户

章节来源

设备管理（设备信息）​

  • 场景：设备列表查询
    • 方法：GET
    • 路径：/device/device/page
    • 请求头：Authorization: Bearer {token}, tenant-id: {adminTenantId}
    • 查询参数：mac、model、status、pageNo、pageSize
    • 断言：状态码 200、total 正数、每页数量不超过 pageSize
  • 场景：设备详情
    • 方法：GET
    • 路径：/device/device/get/{id}
    • 断言：状态码 200、字段完整、id 匹配
  • 场景：设备状态变更
    • 方法：POST
    • 路径：/device/device/update-status
    • 请求体：id、status
    • 断言：状态码 200、状态已更新

章节来源

黑名单管理​

  • 场景：黑名单列表
    • 方法：GET
    • 路径：/blacklist/app-blacklisted/page
    • 请求头：Authorization: Bearer {token}, tenant-id: {adminTenantId}
    • 查询参数：app、channel、region、pageNo、pageSize
    • 断言：状态码 200、total 正数
  • 场景：添加黑名单
    • 方法：POST
    • 路径：/blacklist/app-blacklisted/create
    • 请求体：app、channel、region、reason
    • 断言：状态码 200、返回主键非空
  • 场景：删除黑名单
    • 方法：POST
    • 路径：/blacklist/app-blacklisted/delete
    • 请求体：id
    • 断言：状态码 200、删除成功

章节来源

API 自动化测试与持续集成​

  • GitHub Actions
    • 多 JDK 版本构建，跳过测试阶段以加速流水线（可在需要时调整）。
  • Jenkins
    • 模块化构建与部署脚本，支持镜像构建、推送、回滚与容器运行。
  • 建议
    • 在 CI 中增加 API 自动化步骤（如使用 RestAssured 或 Postman 新版本 Runner），并输出报告与指标。

章节来源

依赖分析​

  • 环境变量依赖
    • Postman/IDE 依赖 http-client.env.json 提供的基础 URL 与 token。
  • Swagger 依赖
    • YudaoSwaggerAutoConfiguration 依赖 SwaggerProperties 提供的元信息。
  • 测试基类依赖
    • BaseDbUnitTest 依赖内存数据库与 MyBatis 配置，适合集成测试。
  • CI/CD 依赖
    • GitHub Actions 与 Jenkins 脚本共同构成自动化流水线。

Mermaid Diagram Code:

graph LR
ENV["http-client.env.json"] --> POSTMAN["Postman/IDE"]
SWAGGER_PROP["SwaggerProperties"] --> SWAGGER_AUTO["YudaoSwaggerAutoConfiguration"]
BASE_DB["BaseDbUnitTest"] --> DB["内存数据库/MyBatis"]
GHA[".github/workflows/maven.yml"] --> ARTIFACTS["制品"]
JENKINS["web-build-deploy.Jenkinsfile.sh"] --> DEPLOY["部署"]

图表来源

性能考虑​

  • 响应时间监控
    • 在 CI 中记录关键接口耗时，建立阈值告警，防止性能退化。
  • 并发与限流
    • 对高频接口进行并发测试，观察限流与熔断策略。
  • 数据量与分页
    • 大数据量分页查询需关注分页大小上限与排序稳定性。

故障排查指南​

  • 环境变量不生效
    • 检查 http-client.env.json 的键名与大小写，确认 Postman/IDE 已选择对应环境。
  • 鉴权失败
    • 确认 Authorization 头与 token 是否正确；检查租户 ID 是否匹配。
  • Swagger 文档空白
    • 确认 Swagger 开关与扫描包配置；检查服务启动日志。
  • 单元测试失败
    • 检查 BaseDbUnitTest 的 SQL 清理与事务回滚；确认测试数据准备与断言逻辑。

章节来源

结论​

通过环境变量统一管理、Swagger 在线调试、单元测试基类支撑以及 CI/CD 自动化，yudao-cloud 形成了完善的 API 测试体系。建议在现有基础上补充 Postman 新版本 Runner 的自动化步骤与性能监控，持续提升测试效率与质量。

附录​

  • 常用 HTTP 方法
    • GET：查询资源
    • POST：创建资源
    • PUT：更新资源
    • DELETE：删除资源
  • 请求头建议
    • Content-Type：application/json
    • Authorization：Bearer {token}
    • tenant-id：{adminTenantId}
  • 请求体格式
    • JSON：键值对，注意字段命名与类型
    • 表单：application/x-www-form-urlencoded
    • 文件上传：multipart/form-data
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答