应建立统一接口规范：一、标准化响应结构（code/msg/data/timestamp）；二、分离HTTP状态码与业务错误码；三、统一分页字段命名；四、资源路径返回完整HTTPS URL；五、精细化跨域配置。
如果您在使用 ThinkPHP6.x 作为后端框架、UniApp 作为前端跨端框架进行混合开发时，发现接口返回不一致、字段缺失或状态码混乱，导致 H5、小程序、App 端行为异常，则可能是由于缺乏统一的数据接口规范。以下是建立稳定、可复用、多端兼容的接口规范的具体操作步骤：
一、统一响应结构设计
为避免各端自行解析不同格式，需强制后端所有接口返回标准化 JSON 结构，包含固定字段，便于 UniApp 统一拦截与错误处理。该结构应屏蔽框架内部异常细节，仅暴露业务层可读信息。
1、在 app/common/Response.php 中定义基础响应类，继承 think\Response，并重写 send 方法。
2、全局中间件中注册统一输出拦截，调用 Response::success() 或 Response::fail() 封装数据。
立即学习“PHP免费学习笔记（深入）”；
3、success 方法返回结构必须包含：code（数值型，200 表示成功）、msg（字符串，非空提示）、data（数组或 null）、timestamp（时间戳）。
4、fail 方法返回结构除 code 改为非 200 值（如 400、500、1001）外，其余字段与 success 保持一致，禁止返回 trace、file、line 等调试信息。
二、状态码与业务错误码分离
HTTP 状态码仅反映通信与协议层结果，业务逻辑错误须通过响应体内的 code 字段表达，防止 UniApp 的 request API 因状态码非 2xx 而直接进入 fail 回调而丢失业务上下文。
1、所有控制器方法内禁止直接 return json() 或 abort(401) 等原生输出。
2、定义业务错误码表 config/error_code.php，例如：['USER_NOT_LOGIN' => 1001, 'TOKEN_EXPIRED' => 1002, 'PARAM_MISSING' => 4001]。
3、在登录验证、参数校验等环节，统一调用 Response::fail(ErrorCode::USER_NOT_LOGIN, '用户未登录')。
4、UniApp 端通过判断 response.data.code === 1001 触发重新登录，而非依赖 status !== 200。
三、分页数据格式标准化
UniApp 的 u-list、uni-pagination 等组件依赖固定字段名解析分页元信息，若 ThinkPHP6 分页器返回的 total、per_page、current_page 等字段与前端预期不一致，将导致翻页失效或总数显示错误。
1、禁用 think\Paginator 默认 JSON 输出，改用自定义分页资源类 PaginateResource。
2、PaginateResource 中显式映射字段：list → data、total → total、page_size → pageSize、page_no → pageNo、last_page → lastPage。
3、控制器中返回 paginate->toArray() 前，先经 PaginateResource::make($paginate)->toArray() 转换。
4、确保 page_no 从 1 开始计数，禁止使用 offset/limit 方式传递页码。
四、文件上传与资源路径统一处理
UniApp 在不同平台对资源路径解析规则不同（H5 支持相对路径，小程序要求 https 协议，App 可能走本地 file://），若 ThinkPHP 直接返回 storage/app/xxx.jpg 等原始路径，将导致图片无法加载。
1、所有文件上传后，使用 Storage::url('xxx.jpg') 获取完整可访问 URL，而非 path() 或 getRealPath()。
2、在 config/filesystems.php 中配置 public 磁盘 driver 为 'public'，并确保 url 前缀为 https://api.example.com/storage/（含协议与域名）。
3、响应中所有 image、avatar、file 字段值，必须为完整 URL，且以 https:// 开头。
4、禁止在响应中返回绝对路径、base64 字符串或本地磁盘路径。
五、跨域与请求头兼容性配置
UniApp 发起的请求在 H5 端默认携带 Cookie，在小程序和 App 端则默认不携带；若 ThinkPHP6 后端未正确识别 Origin 并设置 Access-Control-Allow-Credentials，将导致登录态丢失或预检失败。
1、在 app/middleware/Cors.php 中编写中间件，检测请求头 Origin 是否属于白名单（如 ['https://example.com', 'unpackage://localhost', 'file://']）。
2、对匹配 Origin 的请求，设置响应头：Access-Control-Allow-Origin → 对应 Origin 值、Access-Control-Allow-Credentials → true、Access-Control-Allow-Headers → Content-Type,X-Token,X-Device-Type。
3、在 config/cors.php 中关闭 think-cors 扩展的自动通配符模式，禁止设置 Access-Control-Allow-Origin: * 当 Credentials 为 true 时。
4、UniApp 端发起 request 时，H5 平台需显式设置 withCredentials: true，小程序与 App 平台设为 false。
