把心理测评能力通过开放 API 接到学校的学工系统，真正的难点不在接口能不能调通，而在两个容易被跳过的机制：幂等键和回调重试。这两件事没设计好，测评数据在两套系统之间就会重复、丢失，或者对不上账。
为什么必须有幂等键
学工系统发起一次创建测评任务的请求，遇到网络抖动或超时后会重发。如果服务端每收到一次就新建一个任务，一个学生会凭空多出几条测评记录。幂等键的作用，是让调用方为每次业务操作生成一个唯一标识，服务端认这个键：第一次真正执行，重复请求直接返回上一次的结果，而不是再做一遍。键要能代表同一件事，通常用业务主键加操作类型拼成，而不是每次都换的随机数。
幂等键怎么存和过期
服务端要把用过的键连同处理结果存下来，重复请求命中时直接回放结果。存多久是个取舍：太短，重发窗口一过就失效，起不到防重作用；太长，键表无限膨胀。一般按业务的重试窗口留一段合理时间，按小时或天计，到期清理。键的粒度也要和业务对齐，创建任务、提交答卷、撤回结果各用各的键空间，避免互相覆盖。还有个并发细节：同一个键的两个请求几乎同时到达时，不能两个都判成首次执行，稳妥的办法是给键表加唯一约束，谁先落库谁执行，后到的撞约束后转为回放结果，靠数据库这层兜住并发重复。
回调为什么会失败
测评完成后，橙星云这类平台通常通过回调把结果推回学工系统。可回调这条路同样不可靠：对方服务重启、网关超时、临时报 5xx，都会让一次推送失败。只发一次、失败就丢，学工系统那边的成绩就永远缺了一块。所以回调不能是发出去就不管，得有重试。
回调重试怎么设计才不炸
重试要有退避节奏，失败了不能立刻密集重发，那样对方一恢复就被压垮。常见做法是间隔逐次拉长，几秒、几十秒、几分钟，重试若干次仍失败则转入人工或死信队列。关键在于回调本身要携带幂等键，这样即便平台重复推送，学工系统也能靠键去重，不会把同一份结果记两遍。回调推过去还要能验明身份，通常给回调体加一个签名，接收方校验通过才采信，免得有人伪造回调往系统里塞假成绩。两边都做幂等、都做校验，整条链路才真正安全。
对账不能省
就算幂等和重试都做了，仍要留一条对账兜底。定期比对两边的任务数和结果数，把长时间没回调成功的记录挑出来补推。重试解决的是短时故障，对账解决的是重试用尽后仍遗漏的长尾。两者搭配，学工系统里的心理测评数据和平台侧才能长期保持一致。