ahserver/aidocs/error.md

API 响应工具函数技术文档

本文档描述了一组用于生成标准化 API 响应的 Python 函数。这些函数旨在统一后端接口返回的数据格式，提升前后端交互的一致性和可维护性。

---

目录

• 简介
• 函数说明
  • Error(errno, msg)
  • Success(data)
  • NeedLogin(path)
  • NoPermission(path)
• 响应结构规范
• 使用示例

---

简介

该模块提供四个辅助函数，用于快速构造具有统一结构的 JSON 响应对象。适用于 Web API 开发中常见的成功、错误、登录验证和权限控制场景。

所有函数返回标准字典结构，可直接序列化为 JSON 并返回给客户端。

---

函数说明

Error(errno, msg)

生成表示错误响应的标准结构。

参数

参数名	类型	默认值	说明
errno	str	'undefined error'	错误代码或标识符，用于区分不同类型的错误
msg	str	'Error'	用户可读的错误消息

返回值

{
  "status": "Error",
  "data": {
    "message": "错误信息",
    "errno": "错误编号"
  }
}

示例

Error("404", "资源未找到")
# 返回：
# {
#   "status": "Error",
#   "data": {
#     "message": "资源未找到",
#     "errno": "404"
#   }
# }

---

Success(data)

生成表示操作成功的响应。

参数

参数名	类型	说明
data	any	实际返回的数据内容（可以是字典、列表、字符串等）

返回值

{
  "status": "OK",
  "data": "传入的数据"
}

注意：data 字段的内容由调用者决定，保持灵活性。

示例

Success({"id": 1, "name": "张三"})
# 返回：
# {
#   "status": "OK",
#   "data": {
#     "id": 1,
#     "name": "张三"
#   }
# }

---

NeedLogin(path)

指示客户端当前请求需要用户登录，并可指定跳转路径。

参数

参数名	类型	说明
path	str	登录成功后建议跳转的路径（如 /login）

返回值

{
  "status": "need_login",
  "data": "/login"
}

示例

NeedLogin("/login")
# 返回：
# {
#   "status": "need_login",
#   "data": "/login"
# }

前端可根据此状态重定向至登录页。

---

NoPermission(path)

表示用户没有访问该资源的权限，可附带引导路径。

参数

参数名	类型	说明
path	str	权限不足时建议跳转的页面路径（如 /forbidden 或 /home）

返回值

{
  "status": "no_permission",
  "data": "/forbidden"
}

示例

NoPermission("/home")
# 返回：
# {
#   "status": "no_permission",
#   "data": "/home"
# }

可用于前端展示权限提示或跳转到安全页面。

---

响应结构规范

字段	类型	说明
status	string	响应状态码，取值包括： "OK"：成功 "Error"：通用错误 "need_login"：需要登录 "no_permission"：无权限
data	any	具体数据内容，结构根据 status 而变化

推荐前端通过判断 status 字段进行相应处理。

---

使用示例

# 成功返回用户信息
return Success({
    "user_id": 123,
    "username": "alice",
    "email": "alice@example.com"
})

# 参数校验失败
return Error("VALIDATION_FAILED", "邮箱格式不正确")

# 未登录访问受保护接口
return NeedLogin("/login")

# 用户无权访问管理员功能
return NoPermission("/dashboard")

---

总结

这组函数简化了 API 响应的构建过程，确保前后端通信格式统一、语义清晰。建议在项目中全局使用，避免手动拼接响应结构带来的不一致性。