相亲接口文档 v2.0:一份给单身程序员的婚恋 API 规范

文档版本：v2.0　｜　最后更新：本周末第 7 次相亲后　｜　维护者：一位疲惫的资深单身工程师

v1.0 版本我们采用的核心接口叫「/api/看感觉」，无参数、无文档、无返回值说明，全靠调用方自行体会。线上运行多年，报错率高达 100%，现正式标记为 DEPRECATED。以下是 v2.0 规范，请各方严格遵守。

一、接口总览

Base URL: https://matchmaking.family.local鉴权方式: Bearer Token (由媒人/三姑六婆签发)POST  /api/matchmaking        发起一次相亲GET   /api/profile/{id}       查看对方资料PATCH /api/relation/{id}      更新关系状态POST  /api/relation/{id}/reject   婉拒（高危接口）

注意：Base URL 域名是 .family.local，意味着这是一个内网服务，你无法主动选择暴露给谁——一旦家里有人拿到你的写权限，请求会在节假日自动批量发起。

二、鉴权：媒人 Token

所有请求必须携带媒人签发的 Token。Token 通常包含三个字段：对方身高、对方单位、以及一句「人特别好」。

Authorization: Bearer eyfurenhenhao...// Token payload 解码后{  height: 180(穿鞋量的),  job: 在大公司(全公司30人的那种大),  personality: 特别好(没有别的可夸了)}

Token 有效期极短，通常只够你礼貌拒绝一次。过期后媒人会立即 refresh，并追加一句「这次真的不一样」。

三、核心接口：POST /api/matchmaking

发起一次相亲。请求体建议填写真实信息，但实测大多数调用方会对 avatar 字段做有损压缩。

POST /api/matchmakingContent-Type: application/json{  self_intro: 性格温和，爱好广泛,  avatar: 5年前的自拍.jpg,  expectation: 看缘分}———— 成功响应 200 OK ————{  status: matched,  suggestion: 可以先处处看,  next_step: /api/chat (需自行实现,无文档)}

四、状态码表（重点，建议背诵）

图｜相亲接口常见状态码

200  OK       合适，进入观察期301  Moved    好人卡，永久重定向到「朋友区」302  Found    临时转移话题：你工资多少408  Timeout  已读不回，请求超时412  Failed   前置条件不满足：照片与实物不符429  TooMany  本周第3个，请求过于频繁500  Error    对方妈妈不喜欢你

其中最需要警惕的是 412。该错误常见于线下见面环节，报错信息通常是一阵沉默，以及对方礼貌性地提前看了三次手机。

301 与 302 务必分清：301 是永久重定向（「你是个好人，但我们不合适」），客户端会长期缓存，几乎不可挽回；302 是临时跳转（「先聊聊工作吧」），理论上还能被重新定向回来。

五、高危接口：婉拒

POST /api/relation/{id}/reject 是全系统最危险的操作，没有幂等性保证，且会触发上游（父母、媒人）的重试风暴。

// 你以为的拒绝DELETE /api/relation/{id}  -> 405 Method Not Allowed// 实际发生的POST reject { reason: 没感觉 }  -> 上游返回 500，并自动重试 7 次  -> 每次重试 reason 被改写成:       是不是要求太高了       感情是可以培养的       你看你都多大了

建议配置熔断策略：当单位时间内相亲请求超过阈值，立即返回 503（「最近工作太忙，服务暂不可用」），并进入降级模式——主动报名洗碗、带娃、加班，用繁忙状态码屏蔽后续请求。

六、已知缺陷（Known Issues）

1. 系统不存在 DELETE 方法：你无法真正删除一条相亲记录，它会在每年春节被家族数据库全量备份并重新索引。

2. 分布式一致性问题：你妈口中的你、媒人眼中的你、和真实的你，是三个长期无法达成共识的副本。

3. 文档永远落后于实现：「看缘分」这个字段至今没有任何工程师说得清它的数据类型。

本文档不保证帮你找到对象，只保证在失败时，你能准确报出自己收到的是哪个状态码。

💬 你在相亲里收到过最离谱的状态码是多少？412（照片不符）还是 500（对方妈妈）？评论区提交你的报错日志。