import logger from "./logger.js"; /** * 响应工具类 * 提供统一的响应格式 * * 约定:业务状态一律走 body.code,HTTP 状态码固定 200; * 同时把 code 写进 X-Biz-Code 响应头,便于网关/监控按业务码告警。 */ class ResponseUtil { /** * 成功响应 * @param {Object} ctx - Koa上下文对象 * @param {Object} data - 响应数据 * @param {string} message - 响应消息 */ static success(ctx, data, message = '操作成功') { ctx.status = 200; ctx.set('X-Biz-Code', '0'); ctx.body = { code: 0, msg: message, data, ts: Date.now() }; } /** * 错误响应 * @param {Object} ctx - Koa上下文对象 * @param {string} message - 错误消息 * @param {number} errorCode - 应用错误码 */ static error(ctx, message, data = null, errorCode = 500) { // 根据规则,只要进入controller,http状态码都是200 ctx.status = 200; ctx.set('X-Biz-Code', String(errorCode)); ctx.body = { code: errorCode, msg: message, data, ts: Date.now() }; } /** * 请求参数错误响应 * @param {Object} ctx - Koa上下文对象 * @param {string} message - 错误消息 */ static badRequest(ctx, message = '请求参数错误', data = null) { return ResponseUtil.error(ctx, message, data, 400); } /** * 未授权响应 * @param {Object} ctx - Koa上下文对象 * @param {string} message - 错误消息 */ static unauthorized(ctx, message = '未授权', data = null) { return ResponseUtil.error(ctx, message, data, 401); } /** * 禁止访问响应 * @param {Object} ctx - Koa上下文对象 * @param {string} message - 错误消息 */ static forbidden(ctx, message = '禁止访问', data = null) { return ResponseUtil.error(ctx, message, data, 403); } /** * 资源不存在响应 * @param {Object} ctx - Koa上下文对象 * @param {string} message - 错误消息 */ static notFound(ctx, message = '资源不存在', data = null) { return ResponseUtil.error(ctx, message, data, 404); } /** * 服务器内部错误响应 * * 详细原因只进日志:err.message 可能含 Mongo 连接串、字段名等内部信息, * 直接回传等于把服务端实现细节暴露给前端。 * * @param {Object} ctx - Koa上下文对象 * @param {string|Error} detail - 内部错误详情(仅用于日志) * @param {Object} data - 附加数据 */ static internalError(ctx, detail = null, data = null) { if (detail) { const text = detail instanceof Error ? detail.stack : String(detail); logger.error(`[internal] ${ctx.method} ${ctx.path}: ${text}`); } return ResponseUtil.error(ctx, '服务器繁忙,请稍后重试', data, 500); } } export default ResponseUtil;