推荐使用 success 布尔字段明确标识状态，配合 message、data（仅成功时非 null）、code；必须设置 header('Content-Type: application/json; charset=utf-8')，并确保 UTF-8 编码与非法字符处理。
PHP 返回带提示信息的 JSON 数据结构怎么设计
直接返回 ["msg" => "操作成功", "code" => 200, "data" => $result] 是常见做法，但容易踩坑：前端靠 msg 判断成败不安全，code 值没统一规范，data 在失败时该不该存在也没共识。推荐用明确的顶层状态字段，比如 success 布尔值 + message + data（仅成功时有）+ code（HTTP 状态码或业务码）。这样前端可无脑读 success 字段分支处理。
用 json_encode() 输出时必须设置 header
只 echo 一个 JSON 字符串，浏览器或 AJAX 会当成 text/html 解析，导致前端 response.json() 报错。必须手动加 header('Content-Type: application/json; charset=utf-8');。注意这个 header 要在任何输出之前调用，否则报 “headers already sent”。
- 如果用了框架（如 Laravel、ThinkPHP），通常封装了
response()->json()或json()方法，自动设 header，不用手写 - 纯 PHP 脚本里，
echo json_encode(...)前务必确认没空格、BOM、print、var_dump等提前输出 - 调试时可用
headers_sent($file, $line)检查哪行触发了输出
错误场景下要不要返回 data 字段
建议失败时省略 data，避免前端误用脏数据。比如用户登录失败，data 不该包含半截用户信息。保持响应结构稳定更利于前端类型判断（TypeScript 尤其依赖）。
- 成功：{ "success": true, "message": "登录成功", "data": { "id": 123, "name": "张三" } }
- 失败：{ "success": false, "message": "密码错误", "code": 401 }
- 如果后端需透传部分上下文（如错误字段名），可用额外字段如
errors，而非塞进data
中文乱码和特殊字符问题怎么解
json_encode() 默认不转义中文，但若源数据含 GBK 编码或 JSON 中混入不可见控制字符（如 \u0000），会导致解析失败。关键点是确保输入数据为 UTF-8，且过滤非法字符。
立即学习“PHP免费学习笔记（深入）”；
- 数据库查询结果用
mb_convert_encoding($str, 'UTF-8', 'auto')强制转码 - 对要 JSON 化的数组整体做清理：
array_map('trim', $arr)去首尾空格，再用json_encode($arr, JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE) -
JSON_INVALID_UTF8_SUBSTITUTE会把非法 UTF-8 替换为 ，避免整个 JSON 崩溃
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
'success' => $ok,
'message' => $msg,
'data' => $ok ? $data : null,
'code' => $httpCode
], JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE);
注意 $data 在失败时显式赋 null，比不设更利于前端做 === 判断，也避免某些 JSON 解析器因字段缺失报错。 
