lq/nl-video-api

Fork 0

Files

liqi b88c8b8afa 初始化v1

2025-08-03 00:11:15 +08:00

11 KiB

Raw Permalink Blame History

nl-video-api 错误码定义文档

1. 错误码规范

1.1 错误码格式

错误码采用4位数字格式
第1位表示错误类型：1-业务错误，2-系统错误，3-第三方错误
第2-4位表示具体错误编号

1.2 响应格式

{
  "code": 1001,
  "message": "参数错误：用户名不能为空",
  "data": null
}

2. 通用错误码 (1000-1099)

错误码	错误信息	说明	HTTP状态码
0	成功	请求成功	200
1001	参数错误	请求参数格式错误或缺少必填参数	400
1002	业务逻辑错误	业务规则验证失败	400
1003	认证失败	Token无效或已过期	401
1004	权限不足	用户没有访问该资源的权限	403
1005	资源不存在	请求的资源不存在	404
1006	资源已存在	创建的资源已存在（违反唯一性约束）	409
1007	服务器内部错误	系统内部错误	500
1008	请求方法不允许	HTTP方法不被允许	405
1009	请求频率过高	请求过于频繁，触发限流	429
1010	文件上传失败	文件上传过程中出现错误	400

3. 认证模块错误码 (1100-1199)

错误码	错误信息	说明
1101	用户名或密码错误	登录凭证不正确
1102	账户已被禁用	用户账户状态为禁用
1103	账户已被锁定	用户账户被临时锁定
1104	Token已过期	JWT Token已过期，需要重新登录
1105	Token格式错误	JWT Token格式不正确
1106	用户名已存在	注册时用户名已被使用
1107	邮箱已存在	注册时邮箱已被使用
1108	手机号已存在	注册时手机号已被使用
1109	验证码错误	短信或邮箱验证码不正确
1110	验证码已过期	验证码超过有效期
1111	原密码错误	修改密码时原密码不正确
1112	新密码不能与原密码相同	密码修改规则限制

4. 用户管理模块错误码 (1200-1299)

错误码	错误信息	说明
1201	用户不存在	指定的用户ID不存在
1202	用户名格式错误	用户名长度或格式不符合要求
1203	手机号格式错误	手机号格式不正确
1204	邮箱格式错误	邮箱格式不正确
1205	密码格式错误	密码长度或复杂度不符合要求
1206	昵称格式错误	昵称长度不符合要求
1207	性别参数错误	性别参数值不在允许范围内
1208	VIP等级参数错误	VIP等级不在允许范围内
1209	用户状态参数错误	用户状态参数值不正确
1210	余额不足	用户账户余额不足
1211	积分不足	用户积分不足
1212	VIP已过期	用户VIP会员已过期
1213	不能删除系统用户	系统预设用户不允许删除
1214	批量操作用户数量超限	批量操作的用户数量超过限制

5. 影片管理模块错误码 (1300-1399)

错误码	错误信息	说明
1301	影片不存在	指定的影片ID不存在
1302	影片标题不能为空	影片标题为必填项
1303	影片类型错误	影片类型参数不正确
1304	分类不存在	指定的分类ID不存在
1305	年份格式错误	年份参数格式不正确
1306	国家地区不能为空	国家地区为必填项
1307	时长参数错误	影片时长参数不正确
1308	总集数参数错误	电视剧总集数参数不正确
1309	影片状态参数错误	影片状态参数不正确
1310	封面图片格式错误	封面图片格式不支持
1311	视频文件格式错误	视频文件格式不支持
1312	影片已存在	相同标题和年份的影片已存在
1313	不能删除有剧集的影片	存在剧集的影片不允许删除
1314	评分参数错误	评分必须在0-10之间

6. 剧集管理模块错误码 (1400-1499)

错误码	错误信息	说明
1401	剧集不存在	指定的剧集ID不存在
1402	集数参数错误	集数必须为正整数
1403	剧集标题不能为空	剧集标题为必填项
1404	剧集时长参数错误	剧集时长必须为正数
1405	视频文件不能为空	视频文件为必填项
1406	剧集状态参数错误	剧集状态参数不正确
1407	剧集已存在	相同集数的剧集已存在
1408	集数超出范围	集数不能超过影片总集数
1409	视频文件不存在	指定的视频文件不存在
1410	不能删除最后一集	至少需要保留一集

7. 权限管理模块错误码 (1500-1599)

错误码	错误信息	说明
1501	角色不存在	指定的角色ID不存在
1502	角色名称不能为空	角色名称为必填项
1503	角色编码不能为空	角色编码为必填项
1504	角色编码已存在	角色编码必须唯一
1505	角色等级参数错误	角色等级必须在1-10之间
1506	不能删除系统角色	系统预设角色不允许删除
1507	不能修改系统角色	系统预设角色不允许修改
1508	权限不存在	指定的权限ID不存在
1509	权限名称不能为空	权限名称为必填项
1510	权限编码不能为空	权限编码为必填项
1511	权限编码已存在	权限编码必须唯一
1512	权限类型参数错误	权限类型参数不正确
1513	父权限不存在	指定的父权限ID不存在
1514	不能删除有子权限的权限	存在子权限的权限不允许删除
1515	角色权限分配失败	角色权限关联操作失败

8. 分类管理模块错误码 (1600-1699)

错误码	错误信息	说明
1601	分类不存在	指定的分类ID不存在
1602	分类名称不能为空	分类名称为必填项
1603	分类名称已存在	同级分类名称必须唯一
1604	父分类不存在	指定的父分类ID不存在
1605	不能删除有子分类的分类	存在子分类的分类不允许删除
1606	不能删除有影片的分类	存在影片的分类不允许删除
1607	分类层级过深	分类层级不能超过3级
1608	不能将分类设为自己的子分类	分类层级关系错误

9. 文件上传模块错误码 (1700-1799)

错误码	错误信息	说明
1701	文件不能为空	上传文件为必填项
1702	文件格式不支持	文件格式不在允许范围内
1703	文件大小超限	文件大小超过最大限制
1704	文件上传失败	文件保存过程中出现错误
1705	文件不存在	指定的文件不存在
1706	文件已损坏	文件内容不完整或已损坏
1707	存储空间不足	服务器存储空间不足
1708	文件名包含非法字符	文件名格式不正确

10. 搜索模块错误码 (1800-1899)

错误码	错误信息	说明
1801	搜索关键词不能为空	搜索关键词为必填项
1802	搜索关键词过短	搜索关键词至少2个字符
1803	搜索关键词过长	搜索关键词不能超过50个字符
1804	搜索类型参数错误	搜索类型参数不正确
1805	搜索结果为空	没有找到匹配的结果
1806	搜索服务不可用	搜索引擎服务异常

11. 系统错误码 (2000-2999)

错误码	错误信息	说明
2001	数据库连接失败	无法连接到数据库
2002	数据库查询失败	数据库查询执行失败
2003	数据库事务失败	数据库事务回滚
2004	Redis连接失败	无法连接到Redis服务
2005	缓存操作失败	Redis缓存操作失败
2006	配置文件读取失败	系统配置文件不存在或格式错误
2007	日志写入失败	日志文件写入失败
2008	内存不足	系统内存不足
2009	磁盘空间不足	系统磁盘空间不足
2010	网络连接超时	网络请求超时

12. 第三方服务错误码 (3000-3999)

错误码	错误信息	说明
3001	短信发送失败	短信服务提供商返回失败
3002	邮件发送失败	邮件服务提供商返回失败
3003	支付接口调用失败	支付服务提供商返回失败
3004	视频处理失败	视频转码服务失败
3005	图片处理失败	图片处理服务失败
3006	CDN服务异常	CDN服务不可用
3007	第三方API限流	第三方服务请求频率超限
3008	第三方服务维护	第三方服务正在维护

13. 错误处理最佳实践

13.1 错误信息国际化

// 错误信息支持多语言
var ErrorMessages = map[string]map[int]string{
    "zh-CN": {
        1001: "参数错误",
        1002: "业务逻辑错误",
        // ...
    },
    "en-US": {
        1001: "Parameter error",
        1002: "Business logic error",
        // ...
    },
}

13.2 错误日志记录

// 记录详细的错误信息用于调试
func LogError(code int, message string, err error, context map[string]interface{}) {
    log.Error().
        Int("code", code).
        Str("message", message).
        Err(err).
        Interface("context", context).
        Msg("API Error")
}

13.3 错误响应统一处理

// 统一的错误响应处理
func HandleError(r *ghttp.Request, code int, message string, err error) {
    // 记录错误日志
    LogError(code, message, err, map[string]interface{}{
        "url":    r.URL.String(),
        "method": r.Method,
        "ip":     r.GetClientIp(),
    })
    
    // 返回错误响应
    response.JsonExit(r, code, message)
}

13.4 客户端错误处理建议

// 前端错误处理示例
function handleApiError(error) {
    const { code, message } = error.response.data;
    
    switch (code) {
        case 1003:
            // Token过期，跳转到登录页
            router.push('/login');
            break;
        case 1004:
            // 权限不足，显示提示
            showMessage('权限不足', 'error');
            break;
        default:
            // 其他错误，显示具体错误信息
            showMessage(message, 'error');
    }
}

14. 错误码维护规范

14.1 新增错误码规范

按模块分配错误码范围，避免冲突
错误码必须有明确的含义和说明
错误信息要简洁明了，便于用户理解
新增错误码需要更新文档和测试用例

14.2 错误码废弃流程

标记为废弃状态，但保留定义
在新版本中移除废弃的错误码
更新相关文档和代码

14.3 错误码版本管理

错误码定义纳入版本控制
重大变更需要版本号升级
保持向后兼容性

文档版本: v1.0.0
最后更新: 2024-01-01
维护者: nl-video-api开发团队

11 KiB Raw Permalink Blame History Unescape Escape

nl-video-api 错误码定义文档

1. 错误码规范

1.1 错误码格式

1.2 响应格式

2. 通用错误码 (1000-1099)

3. 认证模块错误码 (1100-1199)

4. 用户管理模块错误码 (1200-1299)

5. 影片管理模块错误码 (1300-1399)

6. 剧集管理模块错误码 (1400-1499)

7. 权限管理模块错误码 (1500-1599)

8. 分类管理模块错误码 (1600-1699)

9. 文件上传模块错误码 (1700-1799)

10. 搜索模块错误码 (1800-1899)

11. 系统错误码 (2000-2999)

12. 第三方服务错误码 (3000-3999)

13. 错误处理最佳实践

13.1 错误信息国际化

13.2 错误日志记录

13.3 错误响应统一处理

13.4 客户端错误处理建议

14. 错误码维护规范

14.1 新增错误码规范

14.2 错误码废弃流程

14.3 错误码版本管理

11 KiB

Raw Permalink Blame History