AI4SE_Practices/AI4SE-survey/tools/documentation/CodeGPT/task7-final-codegpt/sample-api-docs.md

用户管理系统 API 文档

API版本：v1.0.0
生成日期：2025-11-26
生成工具：CodeGPT v3.8.0
技术栈：FastAPI + SQLAlchemy + Pydantic

📋 API 概览

本文档描述用户管理系统核心功能模块的所有API接口。所有接口基于RESTful规范设计，使用JSON格式进行数据交互。

基础信息

• Base URL：http://localhost:8000/api/v1
• 认证方式：Bearer Token（JWT）
• 编码格式：UTF-8
• 时间格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)

通用响应格式

成功响应

{
  "success": true,
  "data": { /* 具体数据 */ },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "detail": "详细错误信息"
  }
}

通用错误码

状态码	错误码	说明
400	BAD_REQUEST	请求参数错误
401	UNAUTHORIZED	未授权
403	FORBIDDEN	无权限访问
404	NOT_FOUND	资源不存在
409	CONFLICT	资源冲突（如用户名已存在）
500	INTERNAL_ERROR	服务器内部错误

🔐 密码相关接口

1. 密码哈希

功能：对原始密码进行SHA256哈希处理。

函数签名：

def hash_password(password: str) -> str

使用场景：内部函数，用于用户注册和密码重置时加密密码。

示例：

from sample_function_docs import hash_password

# 输入
password = "SecurePassword123"

# 输出
hashed = hash_password(password)
# 结果: "3c9909afec25354d551dae21590bb26e38d53f2173b8d3dc3eee4c047e7ab1c1eb8b85103e3be7ba613b31bb5c9c36214dc9f14a42fd7a2fdb84856bca5c44c2"

参数说明：

参数	类型	必填	说明
password	string	✅	原始密码字符串

返回值：

字段	类型	说明
return	string	SHA256哈希值（128字符十六进制字符串）

异常：

异常类型	触发条件	说明
ValueError	密码为空字符串	密码不能为空

---

2. 密码验证

功能：验证原始密码是否与哈希值匹配。

函数签名：

def verify_password(password: str, password_hash: str) -> bool

使用场景：用户登录时验证密码。

示例：

from sample_function_docs import hash_password, verify_password

# 哈希密码
hashed = hash_password("SecurePassword123")

# 验证正确密码
is_valid = verify_password("SecurePassword123", hashed)
# 结果: True

# 验证错误密码
is_valid = verify_password("WrongPassword", hashed)
# 结果: False

参数说明：

参数	类型	必填	说明
password	string	✅	待验证的原始密码
password_hash	string	✅	存储的密码哈希值

返回值：

字段	类型	说明
return	boolean	True表示密码正确，False表示密码错误

复杂度：

• 时间复杂度：O(1)
• 空间复杂度：O(1)

---

👥 用户管理接口

3. 创建用户

功能：创建新用户账户。

HTTP方法：POST /users

函数签名：

def create_user(db: Session, user_data: UserCreate) -> User

请求示例：

POST /api/v1/users HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "SecurePass123",
  "role": "user"
}

Python代码示例：

from sqlalchemy.orm import Session
from sample_function_docs import create_user, UserCreate

# 创建用户数据
user_data = UserCreate(
    username="testuser",
    email="test@example.com",
    password="SecurePass123",
    role="user"
)

# 调用接口
new_user = create_user(db, user_data)

# 返回结果
print(f"用户ID: {new_user.id}")
print(f"用户名: {new_user.username}")

请求参数：

参数	类型	必填	说明	验证规则
username	string	✅	用户名	3-32个字符
email	string	✅	邮箱地址	有效的邮箱格式
password	string	✅	密码	至少8个字符，包含字母和数字
role	string	❌	用户角色	user/admin/guest，默认user

响应示例（成功）：

{
  "id": 1,
  "username": "testuser",
  "email": "test@example.com",
  "role": "user",
  "created_at": "2025-11-26T10:30:00Z",
  "updated_at": "2025-11-26T10:30:00Z",
  "is_active": true
}

响应字段：

字段	类型	说明
id	integer	用户唯一标识符
username	string	用户名
email	string	邮箱地址
role	string	用户角色
created_at	datetime	创建时间（UTC）
updated_at	datetime	最后更新时间（UTC）
is_active	boolean	账户状态

错误响应：

状态码	错误码	说明	示例
400	USERNAME_EXISTS	用户名已存在	{"detail": "用户名已存在"}
400	EMAIL_EXISTS	邮箱已存在	{"detail": "邮箱已存在"}
400	INVALID_USERNAME	用户名格式错误	{"detail": "用户名长度必须在3-32个字符之间"}
400	INVALID_PASSWORD	密码格式错误	{"detail": "密码至少8个字符，包含字母和数字"}
500	CREATE_FAILED	创建失败	{"detail": "创建用户失败: 数据库错误"}

复杂度：

• 时间复杂度：O(1)
• 空间复杂度：O(1)

---

4. 根据ID获取用户

功能：根据用户ID查询用户信息。

HTTP方法：GET /users/{user_id}

函数签名：

def get_user_by_id(db: Session, user_id: int) -> Optional[User]

请求示例：

GET /api/v1/users/1 HTTP/1.1
Host: localhost:8000
Authorization: Bearer <token>

Python代码示例：

from sample_function_docs import get_user_by_id

# 查询用户
user = get_user_by_id(db, user_id=1)

if user:
    print(f"用户名: {user.username}")
    print(f"邮箱: {user.email}")
else:
    print("用户不存在")

路径参数：

参数	类型	必填	说明
user_id	integer	✅	用户ID

响应示例（成功）：

{
  "id": 1,
  "username": "testuser",
  "email": "test@example.com",
  "role": "user",
  "created_at": "2025-11-26T10:30:00Z",
  "updated_at": "2025-11-26T10:30:00Z",
  "is_active": true
}

错误响应：

状态码	错误码	说明
404	USER_NOT_FOUND	用户不存在
400	INVALID_USER_ID	用户ID格式错误（非正整数）

复杂度：

• 时间复杂度：O(1)（数据库主键查询）
• 空间复杂度：O(1)

---

5. 根据用户名获取用户

功能：根据用户名查询用户信息。

HTTP方法：GET /users/by-username/{username}

函数签名：

def get_user_by_username(db: Session, username: str) -> Optional[User]

请求示例：

GET /api/v1/users/by-username/testuser HTTP/1.1
Host: localhost:8000
Authorization: Bearer <token>

Python代码示例：

from sample_function_docs import get_user_by_username

# 查询用户
user = get_user_by_username(db, username="testuser")

if user:
    print(f"用户ID: {user.id}")
    print(f"用户角色: {user.role}")
else:
    print("用户不存在")

路径参数：

参数	类型	必填	说明
username	string	✅	用户名

响应示例（成功）：同"根据ID获取用户"

错误响应：

状态码	错误码	说明
404	USER_NOT_FOUND	用户不存在

性能优化：

• 使用数据库索引优化查询性能
• 时间复杂度：O(log n)（索引查询）

---

6. 获取用户列表（分页）

功能：分页获取用户列表。

HTTP方法：GET /users

函数签名：

def get_users(db: Session, skip: int = 0, limit: int = 10) -> Tuple[List[User], int]

请求示例：

GET /api/v1/users?skip=0&limit=10 HTTP/1.1
Host: localhost:8000
Authorization: Bearer <token>

Python代码示例：

from sample_function_docs import get_users

# 获取第1页（每页10条）
users, total = get_users(db, skip=0, limit=10)

print(f"总用户数: {total}")
for user in users:
    print(f"- {user.username} ({user.email})")

查询参数：

参数	类型	必填	说明	默认值	范围
skip	integer	❌	跳过的记录数	0	>= 0
limit	integer	❌	每页记录数	10	1-100

响应示例（成功）：

{
  "total": 25,
  "users": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "created_at": "2025-11-20T08:00:00Z",
      "updated_at": "2025-11-26T10:00:00Z",
      "is_active": true
    },
    {
      "id": 2,
      "username": "testuser",
      "email": "test@example.com",
      "role": "user",
      "created_at": "2025-11-26T10:30:00Z",
      "updated_at": "2025-11-26T10:30:00Z",
      "is_active": true
    }
  ],
  "page": 1,
  "page_size": 10,
  "total_pages": 3
}

响应字段：

字段	类型	说明
total	integer	总用户数
users	array	用户列表
page	integer	当前页码
page_size	integer	每页记录数
total_pages	integer	总页数

错误响应：

状态码	错误码	说明
400	INVALID_PAGINATION	分页参数错误（skip<0或limit>100）

复杂度：

• 时间复杂度：O(n)（n为limit值）
• 空间复杂度：O(n)

---

7. 更新用户信息

功能：更新指定用户的信息。

HTTP方法：PUT /users/{user_id} 或 PATCH /users/{user_id}

函数签名：

def update_user(db: Session, user_id: int, user_update: Dict) -> Optional[User]

请求示例：

PATCH /api/v1/users/1 HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Authorization: Bearer <token>

{
  "email": "newemail@example.com",
  "role": "admin"
}

Python代码示例：

from sample_function_docs import update_user

# 更新用户信息
update_data = {
    "email": "newemail@example.com",
    "role": "admin"
}

updated_user = update_user(db, user_id=1, user_update=update_data)

if updated_user:
    print(f"用户更新成功！新邮箱: {updated_user.email}")
else:
    print("用户不存在")

路径参数：

参数	类型	必填	说明
user_id	integer	✅	用户ID

请求参数（支持部分更新）：

参数	类型	必填	说明
username	string	❌	新用户名
email	string	❌	新邮箱地址
password	string	❌	新密码（会自动哈希）
role	string	❌	新用户角色
is_active	boolean	❌	账户状态

响应示例（成功）：

{
  "id": 1,
  "username": "testuser",
  "email": "newemail@example.com",
  "role": "admin",
  "created_at": "2025-11-26T10:30:00Z",
  "updated_at": "2025-11-26T15:45:00Z",
  "is_active": true
}

错误响应：

状态码	错误码	说明
404	USER_NOT_FOUND	用户不存在
400	USERNAME_EXISTS	新用户名已被其他用户使用
400	EMAIL_EXISTS	新邮箱已被其他用户使用
500	UPDATE_FAILED	更新失败

注意事项：

• 更新密码时会自动进行哈希处理
• updated_at字段会自动更新为当前时间
• 支持部分更新（只更新提供的字段）

---

8. 删除用户

功能：删除指定用户（软删除：设置is_active=False）。

HTTP方法：DELETE /users/{user_id}

函数签名：

def delete_user(db: Session, user_id: int) -> bool

请求示例：

DELETE /api/v1/users/1 HTTP/1.1
Host: localhost:8000
Authorization: Bearer <token>

Python代码示例：

from sample_function_docs import delete_user

# 删除用户
success = delete_user(db, user_id=1)

if success:
    print("用户删除成功！")
else:
    print("用户不存在或删除失败")

路径参数：

参数	类型	必填	说明
user_id	integer	✅	用户ID

响应示例（成功）：

{
  "success": true,
  "message": "用户删除成功"
}

错误响应：

状态码	错误码	说明
404	USER_NOT_FOUND	用户不存在
500	DELETE_FAILED	删除失败

注意事项：

• 当前实现为软删除（设置is_active=False）
• 如需硬删除（从数据库彻底删除），需要修改函数实现
• 删除操作会在事务中执行，失败会自动回滚

复杂度：

• 时间复杂度：O(1)
• 空间复杂度：O(1)

---

📊 数据模型定义

UserCreate（请求模型）

{
  "username": "string (3-32字符)",
  "email": "string (有效邮箱格式)",
  "password": "string (至少8字符，含字母和数字)",
  "role": "string (user/admin/guest)"
}

User（响应模型）

{
  "id": "integer",
  "username": "string",
  "email": "string",
  "role": "string",
  "created_at": "datetime (ISO 8601)",
  "updated_at": "datetime (ISO 8601)",
  "is_active": "boolean"
}

🔍 使用场景示例

场景1：用户注册流程

# 1. 接收用户注册数据
user_data = UserCreate(
    username="newuser",
    email="newuser@example.com",
    password="SecurePass123"
)

# 2. 创建用户
try:
    new_user = create_user(db, user_data)
    print(f"注册成功！用户ID: {new_user.id}")
except HTTPException as e:
    if e.status_code == 400:
        print(f"注册失败: {e.detail}")

场景2：用户登录验证

# 1. 根据用户名查询用户
user = get_user_by_username(db, username="testuser")

if not user:
    print("用户不存在")
elif not user.is_active:
    print("账户已被禁用")
else:
    # 2. 验证密码
    if verify_password("input_password", user.password_hash):
        print("登录成功！")
    else:
        print("密码错误")

场景3：管理员批量查询用户

# 获取所有管理员用户
page = 1
page_size = 20

while True:
    users, total = get_users(db, skip=(page-1)*page_size, limit=page_size)
    
    admins = [u for u in users if u.role == "admin"]
    
    for admin in admins:
        print(f"管理员: {admin.username} - {admin.email}")
    
    if page * page_size >= total:
        break
    page += 1

🛡️ 安全建议

1. 密码安全：

   • 使用强密码策略（至少8个字符，包含大小写字母、数字和特殊字符）
   • 定期提示用户更新密码
   • 实施密码历史记录，防止重用

2. 认证授权：

   • 所有API接口都应添加JWT认证
   • 实施基于角色的访问控制（RBAC）
   • 敏感操作需要二次验证

3. 数据保护：

   • 使用HTTPS加密传输
   • 敏感字段（如密码哈希）不应在API响应中返回
   • 实施请求限流，防止暴力破解

4. 日志审计：

   • 记录所有用户操作日志
   • 监控异常登录行为
   • 定期审查安全日志

📝 更新日志

v1.0.0 (2025-11-26)

• ✅ 实现8个核心API接口
• ✅ 完整的数据验证和异常处理
• ✅ 支持分页查询
• ✅ 密码安全哈希处理
• ✅ 事务管理和错误回滚

待实现功能

• ⏳ JWT认证中间件
• ⏳ 邮箱验证功能
• ⏳ 密码重置功能
• ⏳ 用户头像上传
• ⏳ 操作日志记录

---

文档生成：CodeGPT v3.8.0
最后更新：2025-11-26
维护者：AI4SE调研小组