密钥、权限、回调都确认过再联调——支付宝AI开放平台的三道前置检查

联调被中断，多数不是业务代码写错，而是密钥环境、接口权限、回调地址这三件事里有一件没落地。写业务代码之前先按顺序做完三道检查：先确认手上的密钥属于沙箱还是生产，再把要调的接口对着控制台的权限列表逐条勾对，最后把回调配好并主动触发一次，确认链路真能收到。三步都过了再写业务代码，能把“联调中途回去补配置”的概率压下来。

三道检查适用于首次接入、切换环境或换人接手。动作是：先确认密钥、AppID 与网关域名属于同一环境；再把要调的接口对着控制台权限列表逐条对齐；最后配置回调并主动触发一次。验证方式分别是打印生效配置、核对勾选状态、在回调日志里看到原始报文且返回成功。边界是：权限生效可能有延迟，回调需公网可达，字段与域名以控制台接入信息页展示为准。

确认当前密钥对应的是哪个环境

沙箱与生产凭证混用是最常见的隐性错误，而且它不会在启动时报错，往往在第一次请求返回签名或应用不匹配时才暴露。判断归属不要靠记忆，靠三个可查的锚点：密钥从哪个环境的页面下载、AppID 与密钥是否在同一应用的同一环境、网关域名是沙箱域名还是生产域名。三者必须指向同一个环境，有任何一个对不上就先停下来。

配置文件里建议把环境写成显式字段，而不是靠文件名或目录去暗示。密钥本身不要写进仓库，用环境变量引用，并在变量名里带环境后缀，避免切换时拿错。

alipay_ai:
  env: sandbox                     # 取值 sandbox / prod，与凭证来源保持一致
  gateway: https://<控制台接入信息页展示的域名>
  app_id: "<当前环境的应用ID>"
  private_key_ref: ALIPAY_AI_SANDBOX_PRIVATE_KEY   # 只引用变量名，不落盘真实密钥

切换环境时逐项过一遍：密钥引用、AppID、网关域名、回调地址、以及用到的证书或公钥。可以在启动日志里打印一次生效配置做自检，只打印 env、gateway、AppID 后六位，不打印密钥明文：

printenv | grep -i alipay_ai | sed 's/=.*/=<hidden>/'

如果日志里 env 是 sandbox，而网关域名看着像生产域名，这就是切换时漏改一项的典型信号，先修正再往下走。

把要调用的接口逐条对着权限列表打勾

权限开通状态要在写代码之前就定下来，不要等接口返回无权限再回头查。做法是先列出这次联调真正要调的接口，一条一条去控制台权限列表里找对应的权限名，权限名以控制台实际展示为准，不要用接口名去猜。

场景          | 要调用的接口（以实际接入为准） | 控制台权限名（以控制台展示为准） | 状态
下单          | /xxx/create                    | xxx.create                       | 已开通
查询          | /xxx/query                     | xxx.query                        | 待确认
回调通知      | /notify/xxx                    | xxx.notify                       | 已开通

缺权限时按这个顺序处理：先确认是不是只是没勾选、可以自助开通；再确认是否要求签约、资质或主体认证；然后确认是否在审核中、需要等待生效；以上都排除后，才联系对接人，并把申请时间、审批状态、涉及接口记在同一行备注里。顺序反了会浪费一轮沟通。

配置回调并主动触发一次验证

回调最怕的是“等业务跑起来才知道收不到”，所以配置完必须主动触发一次，而不是被动等。地址填写有几个要点：必须是公网可达的 HTTPS 地址，路径尽量唯一、便于单独打日志和放行；不要挂在需要登录态的页面上；如果前面有网关或反向代理，先确认该路径没有被拦截、没有被改写请求体。返回体按平台要求的格式返回，通常是固定字符串或约定的成功标识，以接入说明为准。

触发方式优先用控制台提供的测试触发或沙箱下的模拟通知；如果暂时没有，可以手工发一条报文到自己的回调地址，这条只用来验证网络与路由是否通，手工构造的报文签名通常校验不过，不要用它验证签名逻辑：

curl -X POST 'https://<你的回调地址>/notify/alipay-ai' \
  -H 'Content-Type: application/json' \
  -H 'X-Test-Trigger: manual' \
  -d '{"notify_id":"manual-test-001","biz_type":"<替换为实际通知类型>"}'

日志里要能看到这几个观察点：请求是否打到回调路由、原始报文是否完整（含通知 ID 与签名头）、签名校验结果、业务处理结果、以及返回给平台的响应体。少任何一项，都会在真正收不到通知时无法定位。

用最小请求跑通端到端

三项检查都过了，再用一个最小请求跑通，不要一上来就写完整业务流程。通用骨架可以是这样：一个方法、一个必填参数集、一个固定返回解析路径。

POST {gateway}/<接口路径>
Headers:
  Content-Type: application/json
  Authorization: <按平台要求生成的签名或令牌>
Body:
  app_id: <当前环境的应用ID>
  biz_content: { ...只放必填字段... }

期望返回（按实际结构调整）：
  code / msg / request_id / 业务字段所在路径

期望返回不要只写“返回成功”，要写成可以断言的结构：顶层状态码是什么、业务数据挂在哪个字段下、请求 ID 从哪个字段取、出错时错误码落在哪里。这样失败时能直接判断是参数问题还是权限问题。

失败后按配置项逐条回退排查：先看网关域名与环境是否匹配，再看 AppID 与密钥是否同环境，接着看该接口权限是否已生效，然后核对必填参数与编码格式，最后才回到回调链路。从外层配置往里收，通常比从业务代码往外查更快。

把三项检查固化成接入前的确认清单

把上面的动作写成一份带勾选项的清单，换人、换环境时照着走一遍，不用重新踩坑。每项都写明验证动作和失败时的第一处排查位置。

□ 环境确认：打印生效配置，核对 env、网关域名、AppID 三者一致 —— 不通过先查配置加载来源。
□ 密钥确认：确认密钥来源页面与环境一致，变量名带环境后缀 —— 不通过先查环境变量注入。
□ 权限勾对：逐条列出接口与控制台权限名，标注状态 —— 不通过先查控制台勾选状态，再查生效时间。
□ 回调可达：回调地址公网 HTTPS 可达、路径已放行 —— 不通过先查网关与反向代理规则。
□ 回调验证：主动触发一次，日志中看到原始报文与响应体 —— 不通过先查路由是否命中。
□ 最小请求：用必填参数跑通一次，按约定结构断言返回 —— 不通过按环境、凭证、权限、参数顺序回退。

这份清单的价值在于顺序固定：密钥环境放最前，是因为它错了后面所有验证都不可信；回调验证放在业务代码之前，是因为它是最容易拖到最后、也最容易在联调中途把人拽回去的一项。