去年帮朋友的接口公司救过一个火。他们后端用Python写了个库存查询接口，实例前端同事调了一周，接口数据死活对不上。实例我过去一看，接口接口文档写的实例是返回{ "stock": 100}，实际返回的接口是{ "data": { "stock_num": "100"}}。类型是实例字符串，字段名还套了两层。接口这就是实例典型的WebAPI接口设计没规矩。

接口开发第一件事不是接口写代码，是实例定契约。我习惯用OpenAPI规范先把路径、接口方法、实例请求参数、接口响应结构全部写清楚。比如一个用户注册接口，路径就定POST /api/v1/users，请求体里username和password都是必填字符串，响应成功返回201加用户ID，失败返回400加错误码。这个规范文件写完，前端可以拿去生成Mock数据，后端照着实现，测试照着写用例。三拨人不用互相等。

拿Flask写个最简单的例子。路由函数只做三件事：解析参数、调业务逻辑、组装响应。别把业务代码塞进路由里，否则半年后你自己都不想看。

from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/api/v1/users', methods=['POST']) def create_user(): data = request.get_json() username = data.get('username', '').strip() password = data.get('password', '') if not username or len(password) < 6: return jsonify({ 'code': 40001, 'msg': '参数不合法'}), 400 user_id = user_service.register(username, password) return jsonify({ 'code': 0, 'data': { 'user_id': user_id}}), 201 

注意那个code字段。HTTP状态码管传输层，业务状态码管逻辑层，两者分开。很多团队混着用，200里面塞个success: false，前端判断起来很别扭。我的做法是HTTP状态码严格按语义走——400参数错、401没登录、403没权限、404资源不存在、500服务端炸了。响应体里再放一个业务码，比如40001表示用户名已存在，40002表示密码太弱。前端先看HTTP状态码决定要不要弹网络错误提示，再看业务码决定弹什么文案。

版本控制不能省。/api/v1/这个前缀看着啰嗦，等你要改字段名的时候就知道值了。去年我们一个订单接口把total_price改成了amount，直接上了v2路径，v1继续维护了三个月让客户端慢慢迁移。要是没版本号，半夜就得爬起来回滚。

错误处理要统一。我见过一个接口，参数校验失败返回{ "error": "invalid param"}，数据库挂了返回{ "message": "db error"}，字段名都不一样。封装一个全局异常处理器，所有非预期异常都转成标准格式：

@app.errorhandler(Exception) def handle_error(e): app.logger.exception(e) return jsonify({ 'code': 50000, 'msg': '服务器内部错误'}), 500 

日志得打全。请求进来时记下trace_id、路径、参数摘要，响应出去时记下状态码和耗时。有一次线上用户反馈下单失败，我拿着trace_id去日志平台一搜，发现是库存服务超时了。没有这个ID，几万条日志里根本捞不出来。

最后说个容易被忽略的点：接口文档要跟着代码走。我见过太多团队用Swagger生成了文档，但改代码的时候忘了更新注解，文档和实际行为对不上。我的做法是把OpenAPI规范文件纳入代码仓库，每次改接口必须同时改规范文件，CI流水线里加一步校验，不一致就构建失败。麻烦是麻烦了点，但比前端同事拿着过期文档来跟你吵架强。