Web API强势入门：从契约理解到生产级调用实战

1. 这不是“API文档速读课”，而是一份能让你三天内独立调用生产环境接口的实战手记

“Web API 强势入门指南”——看到这个标题，你脑子里可能立刻浮现出两种画面：一种是密密麻麻的HTTP状态码表格和curl命令堆砌的枯燥手册；另一种是某平台首页弹出的“3分钟学会API调用”广告，点进去发现全是“点击复制代码→粘贴运行→恭喜成功”的幻灯片式教学。这两种都不是我要写的。我干这行十一年，从给银行做核心系统对接，到带团队搭IoT设备管理平台，再到帮初创公司重构对外开放的SaaS接口层，亲手写过、改过、修过、压测过、被甲方凌晨三点电话叫起来紧急回滚过的API，少说也有四百多个。我清楚知道，一个刚接触API的人，真正卡住的地方从来不是“GET和POST有什么区别”，而是：

为什么Postman里能跑通的请求，一放进Python脚本就返回401？
为什么文档里写着“必填参数token”，我填了却提示“invalid signature”？
为什么明明按示例拼好了URL，返回却是“404 Not Found”，可路径分明和文档一模一样？

这些不是知识盲区，是 上下文缺失 。Web API从来不是孤立的技术点，它是协议（HTTP）、约定（REST/JSON-RPC）、安全机制（OAuth2/JWT/API Key）、服务端实现逻辑（限流/鉴权/幂等）和客户端工程实践（重试/超时/错误分类）五股绳拧成的一根缆绳。断哪一根，整条链都失效。这篇指南，就是帮你把这五股绳一根一根拆开、摸清纹理、再重新打个牢靠的结。它不教你背RFC文档，但会告诉你什么时候该查RFC；不承诺“零基础秒变大神”，但保证你读完第三章，就能打开任意一家主流云厂商的OpenAPI文档，不靠教程、不问同事，自己把用户列表接口调通并处理好分页和错误。关键词就三个： 强认知、强路径、强落地 ——认知决定你能不能看懂文档背后的潜台词，路径决定你有没有清晰的操作节奏，落地决定你写的代码能不能在真实项目里活过三天。

2. 为什么“入门”必须绕开“Hello World”，直奔真实世界的接口结构？

2.1 真实API的骨架远比教科书复杂：从“单点请求”到“服务契约”

新手常犯的第一个致命错误，是把API当成一个“发个请求拿个数据”的原子操作。这是对Web API本质的严重误读。一个设计良好的Web API，本质上是一份 服务契约（Service Contract） ，它定义的不是“怎么调用”，而是“服务方承诺提供什么能力、在什么条件下、以什么方式交付、失败时如何告知”。这份契约包含五个不可分割的维度：

1. 资源模型（Resource Model） ：它暴露的是什么业务实体？是 /users （集合）还是 /users/{id} （单个）？这个 {id} 是数字ID、UUID，还是邮箱字符串？不同设计意味着客户端要处理完全不同的解析逻辑。比如GitHub API用整数ID，而Stripe用以 cus_ 开头的字符串ID——如果你硬编码 int(user_id) ，对接Stripe时第一行就崩。

2. 交互语义（Interaction Semantics） ：HTTP动词在这里不是语法糖。 GET /orders?status=shipped 是安全、可缓存的查询； POST /orders 是创建新订单，必须带完整数据且不可重复提交； PATCH /orders/{id} 是局部更新，只传要改的字段；而 DELETE /orders/{id} 意味着资源将被移除。我见过太多人用 GET 去触发支付扣款，结果被CDN缓存导致用户被重复扣费——这不是bug，是语义滥用。

3. 数据契约（Data Contract） ：响应体长什么样？是纯JSON对象，还是包裹在 {"data": {...}, "code": 200, "msg": "ok"} 这样的壳里？这个壳是标准规范还是自家约定？字段命名是 snake_case 还是 camelCase ？空值是 null 、 "" 还是直接不返回？这些细节决定了你写JSON解析器时，是写三行 response.json().get("user_name") ，还是得写二十行健壮的 try/except 来兜底所有可能的空值和字段缺失。

4. 安全契约（Security Contract） ：这是新手最懵的环节。 Authorization: Bearer xxx 里的 xxx 从哪来？是静态API Key（如 X-API-Key: abc123 ），还是需要先调 /auth/login 获取Token，再用Token调其他接口？Token有效期多久？刷新机制是什么？有没有IP白名单或Referer校验？去年我帮一家教育公司接入教务系统API，对方文档只写“需携带有效Token”，没提Token要每2小时刷新一次。上线后第三天凌晨，所有自动排课任务全部失败，因为Token过期了——而他们的错误响应是 403 Forbidden ，不是 401 Unauthorized ，根本不像标准OAuth2行为。这就是安全契约不透明带来的灾难。

5. 运维契约（Operational Contract） ：限流规则（100次/分钟？还是5000次/天？）、错误码含义（ 429 Too Many Requests 是限流， 403 是权限不足， 503 Service Unavailable 是服务端过载）、SLA承诺（99.9%可用性）、变更通知机制（重大变更是否邮件通知？是否提前30天公告？）。这些不写在接口文档里，但写在服务协议里。忽略它们，你的程序在流量高峰时就会像纸糊的船一样散架。

提示：下次打开任何API文档，别急着抄代码。先花五分钟，用上面五个维度快速扫描：它的资源怎么组织？动词怎么用？响应数据长啥样？怎么认证？有什么限制？这五分钟，能省你后面八小时的排查时间。

2.2 “强势入门”的底层逻辑：从“调用者思维”切换到“契约共建者思维”

为什么叫“强势入门”？因为真正的入门，不是被动接受文档，而是主动质疑文档、验证契约、补全世界。我带新人时，第一周不让他们写代码，只做三件事：

• 反向推导 ：拿到一个 GET /v1/products?category=electronics&limit=20 接口，要求他们不看文档，仅凭URL和常见REST惯例，猜出：

  • category 是查询参数，类型可能是字符串；
  • limit 是分页参数，值应为正整数；
  • 响应里大概率有 products: [...] 数组和 total_count 字段；
  • 如果 limit 超过100，服务器大概率会截断或报错。
    然后让他们用Postman实际调用，验证猜想。这个过程建立的是 模式识别能力 ，比死记硬背 limit 参数名有用一百倍。

• 错误注入 ：故意把 Authorization 头删掉、把 Content-Type 改成 text/plain 、把JSON Body里一个必填字段设为 null ，观察返回的HTTP状态码、响应体内容、Headers（特别是 X-RateLimit-Remaining 这类运维头）。你会发现，很多API的错误响应比成功响应更“诚实”——它会明确告诉你“缺少X-API-Key头”或“price字段不能为null”，而成功响应往往只是沉默的数据。读懂错误，是理解契约最快的方式。

• 边界测试 ：把 limit 参数设成 0 、 -1 、 1000000 ，把 category 设成超长字符串或SQL注入片段（如 ' OR '1'='1 ），看服务端如何防御。这不仅是安全意识，更是理解服务端校验逻辑的捷径。如果 limit=-1 返回 200 并给你全部数据，说明后端没做参数校验；如果返回 400 并提示“limit must be > 0”，说明校验是健全的。

这种“强势”不是态度嚣张，而是 认知上的主动权 。当你不再把自己当API的“乞讨者”，而是把它当一个需要你去谈判、验证、甚至挑战的合作伙伴时，学习效率会指数级提升。这也是为什么本指南第一章就强调“契约”——因为所有技术细节，都是这个契约的具体实现。

3. 核心细节解析：从URL到Headers，每一个字符都在说话

3.1 URL：不只是路径，它是资源定位与查询意图的双重编码

很多人以为URL就是“地址”，其实它是HTTP协议里最精炼的 语义表达式 。一个典型的API URL： https://api.example.com/v2/users?role=admin&sort_by=created_at&order=desc&page=1&per_page=10 ，拆解如下：

• 协议与域名（ https://api.example.com ） ： https 是强制要求，现代API基本不用HTTP明文传输。 api.example.com 是服务入口，注意它和主站 www.example.com 通常是分离部署的，这意味着Cookie、CORS策略、证书都可能不同。我曾遇到一个案例：前端在 www.example.com 调用 api.example.com ，因未配置CORS，浏览器直接拦截请求，而开发者在Postman里测试一切正常——因为Postman不走浏览器同源策略。

• 版本号（ /v2/ ） ：这是API演进的生命线。 v1 可能用XML， v2 切到JSON； v1 的 /users 返回扁平数据， v2 的 /users 返回嵌套的 {data: [...], pagination: {...}} 结构。 永远显式指定版本号 。不要依赖服务端默认跳转，那会埋下兼容性炸弹。我的经验是：在代码里把 BASE_URL = "https://api.example.com/v2/" 单独抽成常量，而不是拼接字符串。

• 资源路径（ /users ） ：RESTful设计中，它代表资源集合。注意复数形式是惯例（ /users 而非 /user ），这暗示了操作对象是集合。如果路径里出现动词（如 /getUsers ），基本可以判定这不是标准REST，而是RPC风格，后续交互逻辑会完全不同。

• 查询参数（ ?role=admin&sort_by=created_at&order=desc&page=1&per_page=10 ） ：这是客户端向服务端传递“查询意图”的通道。关键细节：

  • role=admin ：这是过滤条件。但 admin 是字符串字面量，还是需要URL编码？如果角色名含空格（如 "super admin" ），必须编码为 role=super%20admin ，否则服务端收到的是 role=super （空格后截断）。我用Python的 urllib.parse.quote() ，Node.js用 encodeURIComponent() ，绝不用手拼。
  • sort_by=created_at ：字段名 created_at 是下划线命名，这很常见，但有些API用驼峰 createdAt 。 命名风格必须严格匹配文档，大小写敏感 。 created_at 和 CREATED_AT 是两个不同字段。
  • page=1&per_page=10 ：这是分页参数。但要注意：有些API用 offset=0&limit=10 （基于偏移），有些用 cursor=abc123 （基于游标）。游标分页更高效，但客户端必须保存上一页返回的 next_cursor 值。我在做日志检索API时，因误用 offset 分页，当数据量超百万时， offset=100000 的查询直接拖垮数据库。

注意：URL长度有限制（通常2000字符左右）。如果查询参数极多（如批量ID查询 id=1&id=2&id=3... ），应改用 POST 方法，把参数放Body里，这是HTTP协议允许的合法做法，不是“偷懒”。

3.2 Headers：那些看不见的“握手协议”与“身份凭证”

Headers是HTTP请求的“元数据信封”，它不携带业务数据，却决定了请求能否被受理。新手常忽略Headers，直到 401 或 403 报错才回头检查。以下是四个必须掌握的核心Header：

• Content-Type ：告诉服务端“我发给你的是什么格式”。

  • 发JSON： Content-Type: application/json 。 必须加 ，否则很多API（尤其是Spring Boot）会直接返回 415 Unsupported Media Type 。
  • 发表单： Content-Type: application/x-www-form-urlencoded （键值对，如 username=john&password=123 ）或 multipart/form-data （上传文件）。
  • 发二进制： Content-Type: image/png 。
    关键点： Content-Type 的值必须和服务端期望的 完全一致 ，包括字符集（如 application/json; charset=utf-8 中的 ; charset=utf-8 有时是必需的）。

• Accept ：告诉服务端“我希望你用什么格式回复我”。

  • Accept: application/json 是最常用，表示“请给我JSON”。
  • 有些API支持 Accept: application/vnd.api+json （JSON:API标准）或 Accept: text/csv （导出CSV）。
  • 如果不设置，服务端可能返回HTML错误页（对开发者友好）或XML（遗留系统），导致JSON解析失败。 永远显式声明 Accept 。

• Authorization ：身份凭证的载体，形式多样：

  • API Key ： Authorization: ApiKey abc123xyz 或 X-API-Key: abc123xyz （后者是非标准但常见）。Key通常是长字符串，需安全存储（环境变量，非代码里硬编码）。
  • Bearer Token ： Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 。这是JWT的典型用法。Token有有效期，必须在过期前刷新。我的做法是：封装一个 get_auth_token() 函数，内部检查Token是否将在5分钟内过期，若是则自动调用刷新接口。
  • Basic Auth ： Authorization: Basic base64(username:password) 。仅用于测试或内网， 生产环境禁用 ，因密码明文传输（虽base64非加密，但极易解码）。

• User-Agent ：标识客户端身份。虽然不是强制，但强烈建议设置。格式如 MyApp/1.0 (contact@myapp.com) 。好处有二：

  1. 服务端监控时，能区分是你的App在调用，还是爬虫或恶意请求；
  2. 遇到问题时，技术支持能快速定位到你的应用。我曾用 User-Agent: MyApp/2.1 (iOS 17.4) 帮客户快速从日志里捞出问题请求。

实操心得：在Postman或curl测试时，务必开启“显示完整请求”（Postman的Console，curl的 -v 参数），亲眼看到Headers是如何被发送的。很多“明明填了Token却401”的问题，根源是Header名拼错了（如 Authtorization 少个 h ）或值前后多了空格。

3.3 请求体（Body）：JSON的“形”与“神”，以及那些坑人的空格和换行

当请求方法是 POST 、 PUT 、 PATCH 时，Body是核心。对JSON API，它不只是数据容器，更是契约的具象化。

• JSON格式的“形” ：必须是严格有效的JSON。

  • 键名必须用双引号： {"name": "John"} ✅， {'name': 'John'} ❌（单引号非法）；
  • 字符串值必须用双引号： "email": "john@example.com" ✅；
  • 最后一个键值对后不能有逗号： {"a": 1, "b": 2,} ❌（尾随逗号非法）；
  • Unicode字符需正确转义： "name": "张三" ✅， "name": "张\u4E09" ✅（等价）。
    我用VS Code的JSON语言模式，它会实时高亮语法错误。绝不手写复杂JSON，用在线工具（如jsonlint.com）格式化校验。

• JSON数据的“神” ：字段语义和约束。

  • 必填 vs 可选 ：文档里标“Required”的字段，在Body里必须存在，且不能为 null （除非文档明确允许）。我见过一个支付接口， amount 字段标“Required”，但开发者传了 "amount": null ，服务端返回 400 ，错误信息却是“amount is missing”——因为 null 在JSON Schema里不等于“缺失”，但某些后端框架会这样处理。解决方案：用 del data['amount'] 删除字段，而不是设为 null 。
  • 数据类型与范围 ： "age": 25 （整数）✅， "age": "25" （字符串）❌（如果文档定义为integer）； "price": 99.99 ✅， "price": 1000000000000 ❌（超出服务端精度限制，可能被截断或报错）。
  • 嵌套结构 ： {"user": {"name": "John", "address": {"city": "Beijing"}}} 。注意层级深度，有些API限制嵌套不超过3层，超深会导致 400 Bad Request 。

• 那些坑人的空白 ：

  • JSON字符串里，键和值之间的空格无关紧要（ "name" : "John" 和 "name":"John" 等价），但 换行和缩进是合法的 ，不影响解析。
  • 真正的坑是： Body末尾的换行符 。某些老旧HTTP库（如早期Python urllib）会在Body末尾自动加 \n ，导致JSON变成 {"a":1}\n ，服务端解析失败。解决方案：发送前用 .rstrip('\n') 清理。
  • 更隐蔽的坑： BOM（Byte Order Mark） 。Windows记事本保存UTF-8文件时可能加BOM（ EF BB BF 字节），JSON解析器会把它当非法字符。用VS Code打开文件，右下角看编码，选“Save with Encoding → UTF-8”（无BOM）。

4. 实操过程：从零开始，用Python调通一个真实电商API（含完整代码与避坑详解）

4.1 选择目标：为什么是Shopify Storefront API？

为了确保实操的真实性，我选了Shopify的Storefront API（公开测试版）。它满足所有“强入门”要求：

• 免费注册商店即可获得API Key；
• 文档清晰，有在线GraphiQL调试器；
• 接口覆盖典型场景（商品查询、添加购物车、下单）；
• 返回标准GraphQL JSON，结构规整，适合初学者解析。
  整个过程，你不需要任何Shopify知识，只需跟着步骤操作。

第一步：获取API凭证

1. 访问 Shopify Partners ，注册免费账号；
2. 创建一个Development Store（开发商店），名字随意，如 my-test-store ；
3. 进入商店后台 → Settings → Apps and sales channels → Develop apps → Create a new app；
4. App name填 MyFirstAPI ，App URL填 https://localhost （本地测试用），Whitelisted redirection URL填 https://localhost/callback ；
5. 在Admin API access scopes里，勾选 read_products （读商品）；
6. 点击Create app，页面会显示 API key (client ID) 和 Admin API access token （长得像 shpca_xxx ）。 把这个Token复制下来，这是你的Bearer Token 。

注意：这个Token是Admin API Token，但Storefront API用的是另一个Token。别慌，我们马上生成。

第二步：创建Storefront Access Token

1. 在刚创建的App页面，找到“Storefront API access tokens”部分；
2. 点击“Generate storefront access token”，输入描述如 dev-token ；
3. 点击Generate，得到一个长字符串Token（如 abcdef1234567890... ）。 这才是我们要用的Authorization Token 。

   提示：Admin Token和Storefront Token用途不同。Admin Token管后台（增删改商品），Storefront Token管前台（顾客浏览、下单）。混淆会导致 403 Forbidden 。

第三步：构造第一个请求——查询商品列表
Shopify Storefront API是GraphQL接口，请求体是GraphQL查询字符串。我们先用最简单的查询：

{
  products(first: 5) {
    edges {
      node {
        id
        title
        description
        variants(first: 1) {
          edges {
            node {
              price
              availableForSale
            }
          }
        }
      }
    }
  }
}

这个查询的意思是：“取前5个商品，返回每个商品的ID、标题、描述，以及第一个变体的价格和是否可售”。

现在，用Python requests实现：

import requests
import json

# 替换为你自己的Storefront Access Token
STOREFRONT_TOKEN = "your_storefront_token_here"
# Shopify商店域名，格式为 your-store-name.myshopify.com
STORE_DOMAIN = "my-test-store.myshopify.com"

# GraphQL Endpoint
GRAPHQL_URL = f"https://{STORE_DOMAIN}/api/2023-10/graphql.json"

# 构造GraphQL查询
query = """
{
  products(first: 5) {
    edges {
      node {
        id
        title
        description
        variants(first: 1) {
          edges {
            node {
              price
              availableForSale
            }
          }
        }
      }
    }
  }
}
"""

# 设置Headers
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Shopify-Storefront-Access-Token": STOREFRONT_TOKEN,  # 注意：Shopify用这个Header，不是Authorization！
    "User-Agent": "MyFirstAPI/1.0 (contact@myfirstapi.com)"
}

# 构造请求体
payload = {
    "query": query
}

# 发送POST请求
response = requests.post(
    GRAPHQL_URL,
    headers=headers,
    json=payload,
    timeout=10
)

# 打印响应
print(f"Status Code: {response.status_code}")
print(f"Response Headers: {dict(response.headers)}")
print(f"Response Body: {response.text}")

# 解析JSON
if response.status_code == 200:
    try:
        data = response.json()
        # 检查是否有errors字段
        if "errors" in data:
            print("GraphQL Errors:", data["errors"])
        else:
            products = data.get("data", {}).get("products", {}).get("edges", [])
            print(f"成功获取 {len(products)} 个商品")
            for edge in products:
                node = edge.get("node", {})
                print(f"- {node.get('title', 'N/A')} | 价格: {node.get('variants', {}).get('edges', [{}])[0].get('node', {}).get('price', 'N/A')}")
    except json.JSONDecodeError as e:
        print("JSON解析失败:", e)
        print("原始响应:", response.text)
else:
    print("请求失败，检查Headers和Token")

第四步：关键避坑与调试技巧
运行这段代码，你可能会遇到以下问题，以及我的解决方案：

实操心得：我写API客户端的第一条铁律是—— 所有外部请求必须包装在 try/except 里，并记录完整的 response.status_code 、 response.headers 和 response.text 。线上出问题时，这三行日志比千行代码更有价值。不要怕日志多，怕的是日志里没有关键信息。

4.2 进阶实操：处理分页与错误重试，让代码在生产环境“活下来”

真实世界不会只有5个商品。当商品数超百，分页是刚需。Shopify Storefront API用 cursor 分页，不是 page / per_page 。

Cursor分页原理 ：

• 首次请求： products(first: 10) ，响应里会返回 pageInfo 对象，包含 hasNextPage 和 endCursor ；
• 下一页请求： products(first: 10, after: "eyJsYXN0X2lkIjoiMTIzNDU2Nzg5MCJ9") ， after 值就是上一页的 endCursor 。

修改代码，实现自动翻页：

def fetch_all_products(token, domain, max_products=100):
    """获取最多max_products个商品，自动处理cursor分页"""
    url = f"https://{domain}/api/2023-10/graphql.json"
    headers = {
        "Content-Type": "application/json",
        "X-Shopify-Storefront-Access-Token": token,
        "User-Agent": "MyFirstAPI/1.0"
    }
    
    all_products = []
    cursor = None  # 首次请求不带cursor
    
    while len(all_products) < max_products:
        # 构造查询，带cursor参数
        if cursor:
            query = f'''
            {{
              products(first: 10, after: "{cursor}") {{
                edges {{
                  node {{
                    id
                    title
                    variants(first: 1) {{
                      edges {{
                        node {{
                          price
                        }}
                      }}
                    }}
                  }}
                }}
                pageInfo {{
                  hasNextPage
                  endCursor
                }}
              }}
            }}'''
        else:
            query = '''
            {
              products(first: 10) {
                edges {
                  node {
                    id
                    title
                    variants(first: 1) {
                      edges {
                        node {
                          price
                        }
                      }
                    }
                  }
                }
                pageInfo {
                  hasNextPage
                  endCursor
                }
              }
            }'''
        
        payload = {"query": query}
        
        try:
            response = requests.post(url, headers=headers, json=payload, timeout=15)
            response.raise_for_status()  # 抛出4xx/5xx异常
            
            data = response.json()
            if "errors" in data:
                print("GraphQL错误:", data["errors"])
                break
                
            products_data = data.get("data", {}).get("products", {})
            edges = products_data.get("edges", [])
            page_info = products_data.get("pageInfo", {})
            
            # 添加当前页商品
            all_products.extend(edges)
            print(f"已获取 {len(all_products)} 个商品...")
            
            # 检查是否还有下一页
            if not page_info.get("hasNextPage") or not page_info.get("endCursor"):
                break
            cursor = page_info["endCursor"]
            
        except requests.exceptions.RequestException as e:
            print("网络请求异常:", e)
            break
        except json.JSONDecodeError as e:
            print("JSON解析异常:", e)
            break
        except Exception as e:
            print("未知异常:", e)
            break
    
    return all_products[:max_products]  # 截取到max_products个

# 调用
products = fetch_all_products(STOREFRONT_TOKEN, STORE_DOMAIN, max_products=50)
print(f"最终获取 {len(products)} 个商品")

错误重试机制 ：网络不稳定是常态。简单粗暴的 while True 重试会雪崩。我用指数退避（Exponential Backoff）：

import time
import random

def robust_request(url, headers, payload, max_retries=3):
    """带指数退避的健壮请求"""
    for attempt in range(max_retries + 1):
        try:
            response = requests.post(url, headers=headers, json=payload, timeout=10)
            if response.status_code in [200, 201]:
                return response
            elif response.status_code in [429, 502, 503, 504]:  # 限流或服务端临时错误
                if attempt < max_retries:
                    # 计算退避时间：2^attempt + 随机抖动
                    backoff = (2 ** attempt) + random.uniform(0, 1)
                    print(f"请求失败 {response.status_code}，{backoff:.2f}秒后重试...")
                    time.sleep(backoff)
                    continue
                else:
                    raise Exception(f"重试{max_retries}次后仍失败: {response.status_code}")
            else:
                # 其他错误（如400, 401）不重试，立即抛出
                response.raise_for_status()
                
        except requests.exceptions.RequestException as e:
            if attempt < max_retries:
                backoff = (2 ** attempt) + random.uniform(0, 1)
                print(f"网络异常 {e}，{backoff:.2f}秒后重试...")
                time.sleep(backoff)
            else:
                raise e
    
    return None  # 不会执行到这里，上面已raise

注意：重试只针对 临时性错误 （429限流、502/503/504服务端故障）。对于400（参数错）、401（认证失败）、403（权限不足），重试毫无意义，只会浪费资源。判断错误类型，是重试策略的灵魂。

5. 常见问题与排查技巧实录：那些让我凌晨三点爬起来的“经典瞬间”

5.1 “401 Unauthorized”：Token明明是对的，为什么还报错？

这是最高频的报错，原因五花八门。我整理了一个速查表，按发生概率排序：

提示：当 401 出现时， 第一反应不是改代码，而是用curl命令行复现 ：
curl -X POST https://api.example.com/v1/data \ -H "Authorization: Bearer your_token_here" \ -H "Content-Type: application/json" \ -d '{"key":"value"}'
如果curl也401，问题一定在Token或网络；如果curl成功而代码失败，问题一定在代码的Headers构造逻辑。

5.2 “400 Bad Request”：参数都对了，为什么还说“Bad Request”？

400 是服务端说“我听不懂你的话”。原因往往藏在细节里：

• Content-Type不匹配 ：你发了JSON，但Header里写 Content-Type: text/plain 。服务端尝试用纯文本解析器读JSON，必然失败。
• JSON语法错误 ：多了一个逗号、少了一个引号、Unicode字符未转义。用 json.loads() 在Python里预校验。
• 字段名大小写错误 ：文档写`"user