TP6接口返回状态码规范要求HTTP状态码与业务状态码分层使用：HTTP码（如200/404/500）标识传输层结果，业务码（如1/-1/1001）表达逻辑结果；需配置集中管理、封装统一响应函数show()、控制器中规范调用，并严格区分二者职责边界。

TP6 接口返回状态码规范的核心是分层统一、语义明确、可维护强：HTTP 状态码管传输层（如 200/404/500），业务状态码管逻辑层（如 1 表成功、-1 表未登录），两者不混用、不替代。

一、定义清晰的业务状态码配置

在 config/ 目录下新建 status.php 或 code.php，集中管理所有业务含义：

• 避免硬编码数字，例如不用 return ['code' => 1, ...]，而用 config('code.success')
• 推荐结构含「语义键 + 数值 + 可选描述」，例如：
  

  return [
      'success'      => 1,
      'error'        => 0,
      'need_login'   => -1,
      'invalid_param'=> 1001,
      'not_found'    => 1002,
      'rate_limit'   => 1003,
  ];

• 配置文件中不写逻辑，只作映射；后续所有控制器、服务层都通过 config('code.xxx') 引用

二、封装统一响应函数（推荐放在 app/common.php）

定义一个轻量、无副作用的全局函数，兼顾灵活性与一致性：

• 函数签名建议为 show($code, $msg = '', $data = [], $httpCode = 200)
• $code 传业务码（如 config('code.success')），$httpCode 仅控制 HTTP 层（默认 200，错误时可设 400/422/500）
• 若 $msg 为空且该 $code 在配置中有对应文案，则自动填充，提升可维护性
• 最终强制走 json()，不拼接字符串、不 echo、不 return 数组

三、控制器中规范使用方式

禁止直接 return ['code'=>1, 'msg'=>'ok'] 或 echo json_encode(...)，应统一调用封装函数：

• 成功返回：return show(config('code.success'), '操作成功', $user);
• 参数错误：return show(config('code.invalid_param'), '手机号格式不正确', [], 400);
• 需登录：return show(config('code.need_login'), '请先登录', null, 401);
• 数据库查不到：return show(config('code.not_found'), '用户不存在', [], 404);

四、注意 HTTP 状态码与业务码的协作边界

二者职责分明，不可互相覆盖或隐藏问题：

• HTTP 200 表示请求被服务器正常接收并处理完毕，不代表业务成功（业务成功由 code=1 表达）
• HTTP 4xx/5xx 应用于客户端错误或服务端异常场景，例如参数校验失败用 400、资源不存在用 404、内部错误用 500
• 不要为所有失败都返回 200 + code=0 —— 这会让前端无法区分网络失败、超时、服务崩溃等真实问题
• 前端可通过响应头 Status 或 Axios 的 response.status 快速识别传输层问题，再解析 body.code 做业务分支