如何让未创建用户阶段的短信验证API更符合RESTful规范？

看起来你卡在了用户未创建阶段的身份验证端点RESTful设计上，这确实是很多API都会遇到的典型场景——毕竟身份验证往往是正式用户创建的前置步骤。我给你几个实用的优化思路，既贴合RESTful的资源导向核心，又完美适配你的业务流程：

思路1：把验证流程抽象为「验证请求资源」 #

RESTful的核心是资源而非动作，所以我们可以把“发送验证码-验证验证码”整个流程，看作是对「验证请求」这个资源的创建和状态更新：

• 发送验证码：用POST /verification-requests，请求体携带目标手机号。服务器收到后，创建一个新的验证请求资源（包含唯一ID、手机号、过期时间等元数据），返回201 Created状态码和该资源的详情，同时触发短信发送逻辑。这样完全符合“创建资源”的语义，避免了URL里的动词。
• 验证验证码：用PUT /verification-requests/{requestId}，请求体携带用户输入的验证码。服务器会根据requestId找到对应的验证请求，检查验证码的有效性和过期时间：
  • 验证通过：更新该验证请求的状态为「已验证」，同时在响应体中返回session token；
  • 验证失败：返回400 Bad Request（验证码错误）或404 Not Found（请求已过期/不存在）等合适的状态码。

思路2：用更简洁的「手机号验证资源」 #

如果觉得verification-requests太冗长，可以用更聚焦的资源名/phone-verifications：

• POST /phone-verifications：提交手机号，创建一条手机号验证记录，返回验证ID和过期时间，同时发送短信；
• PUT /phone-verifications/{verificationId}：提交验证码，验证通过后返回session token。

这种方式更直观，直接点明资源是“手机号验证”，同样符合RESTful的资源导向原则。

思路3：结合「预注册用户资源」 #

考虑到后续要创建正式用户，你也可以把验证流程和用户预注册绑定，抽象出/user-pre-registrations资源：

• POST /user-pre-registrations：提交手机号，创建一个预注册用户资源（包含手机号、验证状态、过期时间），返回预注册ID，同时发送验证码；
• PUT /user-pre-registrations/{preRegId}：提交验证码，验证通过后返回session token，同时标记该预注册资源为「已验证」。后续用户领取礼物时，就可以基于这个已验证的预注册资源直接创建正式用户，减少重复操作。

额外细节建议 #

• 尽量避免在URL中使用动词（比如原有的sendSmsCode、verifyUser），用HTTP方法（POST/PUT）+资源名来表达动作语义；
• 响应中要返回资源的关键元数据，比如验证请求的过期时间，方便客户端处理超时重发的场景；
• 针对频繁发送短信的情况，返回429 Too Many Requests状态码，配合Retry-After头限制请求频率；
• 验证通过后的session token，建议放在响应体中返回（而非header），更符合客户端的常规处理习惯。

示例流程（基于思路1） #

1. 客户端请求发送验证码：

   POST /verification-requests
   Content-Type: application/json
   
   {
     "phoneNumber": "+1234567890"
   }
   

   服务器响应：

   201 Created
   Content-Type: application/json
   
   {
     "id": "vr_abc123",
     "phoneNumber": "+1234567890",
     "status": "pending",
     "expiresAt": "2024-05-20T15:30:00Z"
   }
   

2. 客户端提交验证码验证：

   PUT /verification-requests/vr_abc123
   Content-Type: application/json
   
   {
     "code": "123456"
   }
   

   验证通过时服务器响应：

   200 OK
   Content-Type: application/json
   
   {
     "sessionToken": "st_xyz789",
     "expiresAt": "2024-05-21T15:30:00Z"
   }
   

内容的提问来源于stack exchange，提问作者Mark