软件测试接口测试从入门到精通：RESTful API设计规范

03 RESTful API 设计规范 - 设计优雅的接口本章目标理解RESTful架构风格掌握URL设计规范、HTTP方法语义学会阅读和测试RESTful接口。3.1 什么是RESTful生活中的类比想象一个图书馆管理系统传统方式非RESTful /getUserInfo?id1 → 获取用户信息 /createUser → 创建用户 /updateUser → 更新用户 /deleteUser?id1 → 删除用户 RESTful方式 GET /users/1 → 获取用户信息 POST /users → 创建用户 PUT /users/1 → 更新用户 DELETE /users/1 → 删除用户RESTful的核心思想用URL定位资源用HTTP方法描述对资源的操作。REST的定义RESTRepresentational State Transfer表现层状态转换是一种软件架构风格由Roy Fielding在2000年提出。资源 ResourcesURL表示表现层 RepresentationJSON/XML状态转换 State TransferHTTP方法无状态 Stateless每次请求独立3.2 RESTful设计六大原则原则1URL表示资源不是动作错误动词在URL中正确名词表示资源GET /getUser?id1GET /users/1POST /createUserPOST /usersPOST /updateUserPUT /users/1GET /deleteUser?id1DELETE /users/1原则2用HTTP方法表示操作HTTP方法操作幂等性示例GET读取资源是GET /users获取用户列表POST创建资源否POST /users创建新用户PUT全量更新是PUT /users/1替换用户1的全部信息PATCH部分更新否PATCH /users/1只更新用户1的邮箱DELETE删除资源是DELETE /users/1删除用户1原则3使用复数名词/users ✓ 正确 /user ✗ 错误用复数 /Users ✗ 错误小写 /getUsers ✗ 错误不要有动词原则4正确的HTTP状态码成功 → 返回 2xx200 OK, 201 Created, 204 No Content客户端错误 → 返回 4xx400, 401, 403, 404, 422服务端错误 → 返回 5xx500, 502, 503原则5使用查询参数过滤、排序、分页GET /users?roleadminsortnamepage1size20 ↑ ↑ ↑ ↑ 过滤条件 排序字段 页码 每页数量原则6版本控制/api/v1/users → API版本1 /api/v2/users → API版本2 或放在Header中 Accept: application/vnd.api.v1json3.3 RESTful URL设计实战电商系统接口设计功能HTTP方法URL说明用户模块获取用户列表GET/api/v1/users支持分页、筛选获取单个用户GET/api/v1/users/1用户ID为1创建用户POST/api/v1/usersBody传用户数据更新用户PUT/api/v1/users/1全量更新部分更新PATCH/api/v1/users/1部分字段更新删除用户DELETE/api/v1/users/1软删除或硬删除获取用户订单GET/api/v1/users/1/orders嵌套资源商品模块获取商品列表GET/api/v1/products支持分类筛选获取商品详情GET/api/v1/products/100商品ID为100搜索商品GET/api/v1/products?keyword手机关键词搜索订单模块创建订单POST/api/v1/orders从购物车创建获取订单GET/api/v1/orders/2024001订单号取消订单PUT/api/v1/orders/2024001/status更新状态获取订单商品GET/api/v1/orders/2024001/items订单明细3.4 请求和响应的数据格式标准响应结构{ code: 0, message: success, data: { id: 1, name: 张三, email: zhangsanexample.com } }分页响应结构{ code: 0, message: success, data: { list: [ {id: 1, name: 张三}, {id: 2, name: 李四} ], pagination: { page: 1, size: 20, total: 100, totalPages: 5 } } }错误响应结构{ code: 1001, message: 用户名或密码错误, data: null, details: { field: password, reason: 密码长度不足 } }3.5 RESTful API测试要点测试维度URL规范是否使用复数名词、是否无动词、嵌套资源是否合理HTTP方法GET只读、POST创建、PUT/PATCH更新、DELETE删除状态码2xx成功、4xx客户端错误、5xx服务端错误响应格式统一结构、错误信息清晰、分页信息完整测试检查清单检查项说明通过标准URL设计是否使用名词复数/users✓/getUsers✗HTTP方法方法是否语义正确GET获取、POST创建、PUT更新、DELETE删除状态码返回码是否合理创建返回201、删除返回204响应格式结构是否统一包含code、message、data错误处理错误信息是否友好包含错误码和详细说明分页分页参数是否支持page、size、total过滤排序查询参数是否支持?roleadminsortname版本控制API是否有版本/api/v1/...3.6 实战分析一个RESTful接口文档接口文档示例# 用户管理接口 ## 获取用户列表 GET /api/v1/users 请求参数: page: 页码 (默认1) size: 每页数量 (默认20) role: 角色筛选 (可选) 响应: 200 OK { code: 0, data: { list: [...], pagination: {...} } } ## 获取单个用户 GET /api/v1/users/{id} 路径参数: id: 用户ID 响应: 200 OK - 用户存在 404 Not Found - 用户不存在 ## 创建用户 POST /api/v1/users 请求体: { name: 张三, email: zhangsanexample.com, role: user } 响应: 201 Created { code: 0, data: {id: 1, name: 张三, ...} } 400 Bad Request - 参数错误 409 Conflict - 邮箱已存在 ## 更新用户 PUT /api/v1/users/{id} 请求体: { name: 张三, email: zhangsanexample.com, role: admin } 响应: 200 OK 404 Not Found ## 删除用户 DELETE /api/v1/users/{id} 响应: 204 No Content 404 Not Found测试用例设计GET /users正常分页、带筛选条件、边界值page0GET /users/1存在的用户、不存在的用户、非法IDabcPOST /users正常创建、缺少必填字段、邮箱格式错误、重复邮箱PUT /users/1正常更新、更新不存在的用户、非法字段值DELETE /users/1正常删除、删除不存在的用户、无权限删除3.7 非RESTful接口怎么办现实情况不是所有接口都是纯RESTful的常见变体纯RESTful严格遵循6原则类RESTful大部分RESTful少量自定义RPC风格HTTP全用POSTURL含动作GraphQL单一端点查询语言类RESTful示例POST /api/v1/users/1/enable → 启用用户自定义动作 POST /api/v1/users/1/disable → 禁用用户自定义动作 POST /api/v1/orders/1/refund → 订单退款自定义动作测试策略理解设计意图按实际规范测试不必强求纯RESTful。3.8 本章小结RESTful核心要点URL设计名词复数、无动词、嵌套资源HTTP方法GET读 POST建 PUT PATCH更新 DELETE删状态码201创建 204删除 404不存在响应格式统一结构、错误清晰、分页完整课后练习 设计题为一个博客系统设计RESTful API包含文章、评论、标签、用户四个模块。分析题分析你工作中或常用的API判断是否符合RESTful规范有哪些可以改进的地方。测试题针对上面的用户管理接口文档写出至少10个测试用例包含正常和异常场景。3.9 下章预告下一章我们将学习常见接口类型和数据格式JSON、XML、GraphQL等以及如何在接口测试中使用它们RESTful不是教条而是一种优雅的设计哲学。理解它你就能设计出让人愉悦的API。