零基础入门Python13RESTful接口设计从需求写出接口契约本篇图解程序执行顺序这张图对应代码的执行顺序。先说清输入、处理和输出再解释语法细节初学时不容易迷路。一、上一篇课后练习讲解路径参数可以先判断固定前缀再取最后一段defdo_GET(self):print(User-Agent:,self.headers.get(User-Agent))ifself.path.startswith(/api/tasks/):task_id_textself.path.removeprefix(/api/tasks/)iftask_id_text1:self.send_json(200,{id:1,title:学习HTTP,done:False},)else:self.send_json(404,{code:TASK_NOT_FOUND,message:任务不存在},)return这里仍是教学用简化路由。真实框架会自动提取并转换路径参数。可执行验收答案下面的实现补上三个错误边界路径缺少 id、id 不是正整数、任务不存在。它可以直接替换上一练习中的do_GET分支fromurllib.parseimporturlsplitdefparse_task_path(path:str)-tuple[int|None,dict|None]:parts[partforpartinurlsplit(path).path.split(/)ifpart]iflen(parts)!3orparts[:2]![api,tasks]:returnNone,{code:NOT_FOUND,message:路径不存在}try:task_idint(parts[2])exceptValueError:returnNone,{code:INVALID_ID,message:任务编号必须是整数}iftask_id0:returnNone,{code:INVALID_ID,message:任务编号必须大于0}returntask_id,Noneforpathin[/api/tasks/1,/api/tasks/abc,/api/tasks/0,/wrong]:print(path,parse_task_path(path))预期/api/tasks/1返回 id1其他三种分别返回INVALID_ID或NOT_FOUND。查询参数不能改变路径解析结果响应层再把错误映射为 400/404解析函数不要直接写 socket。二、本篇成果不急着写框架代码先把任务管理器需求整理为可执行的REST接口契约资源名称、方法、URL、请求体、响应体、状态码、分页和错误格式。契约是前后端共同遵守的约定。三、资源使用名词不推荐/getTasks /createTask /deleteTask?id3推荐GET /api/v1/tasks POST /api/v1/tasks GET /api/v1/tasks/3 PATCH /api/v1/tasks/3 DELETE /api/v1/tasks/3URL表达资源HTTP方法表达操作。tasks使用复数编号放路径中。v1是版本前缀。四、任务字段约定任务资源{id:3,title:学习REST,priority:high,due_date:2026-08-20,done:false,created_at:2026-08-06T10:00:0008:00}字段约束title长度1到120priority只能是high、medium、lowdue_date可为空非空时使用YYYY-MM-DDdone由布尔值表示id和created_at由服务器生成创建时不接受客户端指定。五、创建任务请求POST /api/v1/tasks Content-Type: application/json{title:学习REST,priority:high,due_date:2026-08-20}成功返回201和完整资源。标题为空返回400{code:VALIDATION_ERROR,message:请求数据不合法,details:{title:标题不能为空}}错误结构必须稳定前端才能按code处理而不是解析自然语言。六、列表、分页、筛选和排序GET /api/v1/tasks?page1size20donefalsepriorityhighorderdue_date响应{page:1,size:20,total:37,items:[]}page从1开始size限制最大100防止一次读取全部数据筛选条件放查询参数排序字段使用白名单不能把任意字符串直接拼入SQL。七、详情、修改和删除详情GET /api/v1/tasks/3部分修改PATCH /api/v1/tasks/3 Content-Type: application/json{done:true}PATCH只修改提交字段PUT通常表示完整替换。删除成功HTTP/1.1 204 No Content204不返回JSON正文。不存在统一返回404 TASK_NOT_FOUND。八、幂等与重复请求GET、PUT、DELETE通常应具备幂等性重复同一请求资源最终状态一致。POST创建通常不幂等网络重试可能重复创建。支付等重要创建接口会使用幂等键本课程后面再展开。删除一个已删除任务可以返回404关键是契约明确且保持一致。九、接口契约表功能方法URL成功常见错误创建POST/api/v1/tasks201400列表GET/api/v1/tasks200400详情GET/api/v1/tasks/{id}200404修改PATCH/api/v1/tasks/{id}200400/404删除DELETE/api/v1/tasks/{id}204404写框架代码前先完成这张表可以避免路由命名、状态码和字段在开发中不断变化。十、本篇验收URL使用资源名词而非动作HTTP方法表达CRUD创建成功返回201删除成功返回204且无正文列表包含分页元数据错误响应有稳定code能解释PATCH与PUT区别为输入、输出和错误都写出契约。十一、课后练习为任务资源增加“标签”子资源设计新增标签、删除标签、查看某任务标签的接口再设计按标签筛选任务的查询参数。必须写出方法、URL、请求体、成功状态码和至少一种错误响应。下一篇会把契约中的任务和标签真正存入SQLite。实战补充REST 契约表任务接口的契约应先写清楚再实现GET /tasks 返回列表POST /tasks 返回 201PATCH /tasks/{id} 返回更新对象DELETE 返回 204。错误响应包含 code、message 和 request_id。{data:{id:1,title:学习 SQL,done:false},request_id:req-1}验收每个方法的成功和失败状态码课后练习为分页响应补 items、next_cursor 和 has_more下一篇把数据写入 SQLite。本篇结束完整模块文件本节不是代码片段而是本篇结束时该模块的完整版本。请先备份旧文件再整体替换替换后重新运行本篇命令和测试。阅读时重点看本篇新增的函数、事务边界和错误处理未涉及的代码先不要自行删减。本篇完整示例GET /api/v1/articles POST /api/v1/articles GET /api/v1/articles/42 PATCH /api/v1/articles/42 DELETE /api/v1/articles/42