用户认证成功或失败时的服务端响应设计问题咨询

绝对不要只返回True/False，这是仅适合demo、临时测试脚本的极简写法，只要是面向生产环境、需要长期迭代的服务，必须设计结构化响应，原因和具体方案如下：

为什么纯布尔值响应不可用 #

• 失败场景下信息完全不足：客户端拿到False根本无法判断失败原因，是账号不存在？密码错误？账号被封禁？登录凭据过期？还是需要二次验证？如果所有失败都统一弹“认证失败”，用户体验极差，开发排查问题也没有任何线索。
• 浪费HTTP协议本身的语义设计：不要所有请求不管结果全返回200状态码，认证场景要配合标准HTTP状态码传递基础结果：凭据格式非法返回400，身份校验不通过返回401，账号无对应资源权限返回403，请求触发限流返回429，服务端内部错误返回500。

推荐的结构化响应结构 #

核心保留三个固定字段，所有接口保持统一格式，降低客户端解析成本：

• code：业务状态码，和HTTP状态码区分开，用来标记具体的业务结果，比如0代表认证成功，1001代表账号密码错误，1002代表账号被封禁，1003代表需要完成二次验证。客户端可以根据这个码做精准逻辑跳转，不需要解析提示文案判断分支。
• message：面向开发者排查、或者面向前端展示的提示文本，注意不要泄露敏感信息，比如不要明确返回“账号不存在”避免被攻击者遍历扫库，统一返回“账号或密码错误”即可，具体错误细节记在服务端日志里。
• data：业务载荷字段，认证成功时返回token、用户基础信息、过期时间等内容；认证失败时可以返回辅助信息，比如剩余重试次数、账号解封剩余时间、二次验证所需的临时凭据等。

认证成功响应示例 #

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "message": "认证成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx",
    "expires_in": 7200,
    "user_info": {
      "uid": 10086,
      "username": "demo_user",
      "avatar": "/static/avatar/default.png"
    }
  }
}

普通认证失败响应示例（密码错误场景） #

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": 1001,
  "message": "账号或密码错误",
  "data": {
    "retry_remaining": 2,
    "lock_duration": 300
  }
}

特殊认证失败响应示例（需要二次验证场景） #

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": 1003,
  "message": "请完成短信验证",
  "data": {
    "verify_type": "sms",
    "tmp_ticket": "7f9d2xka8xxx"
  }
}

补充说明 #

如果是做一次性的内部工具、快速验证逻辑的测试接口，直接返回True/False完全没问题，能省很多事；但只要是面向C端用户、需要多端配合迭代的正式服务，统一结构化响应是必须做的基础设计，前期偷的懒都会变成后期联调、排错、改需求时的坑。

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