第30天：RESTful API设计

# day30_restful_api.py
# 功能：简单的RESTful API实现

from flask import Flask, request, jsonify
from datetime import datetime
import uuid

app = Flask(__name__)

# 模拟数据库
users_db = {}

# 初始化一些测试数据
def init_data():
    """初始化测试数据"""
    users = [
        {"name": "张三", "email": "zhang@example.com", "role": "admin"},
        {"name": "李四", "email": "li@example.com", "role": "user"},
        {"name": "王五", "email": "wang@example.com", "role": "user"},
    ]

    for user_data in users:
        user_id = str(uuid.uuid4())
        users_db[user_id] = {
            "id": user_id,
            **user_data,
            "created_at": datetime.now().isoformat(),
            "updated_at": datetime.now().isoformat()
        }

init_data()


def success_response(data=None, message="操作成功", status_code=200):
    """
    成功响应格式

    参数：
        data: 返回的数据
        message: 提示信息
        status_code: HTTP状态码
    """
    response = {
        "status": "success",
        "message": message
    }

    if data is not None:
        response["data"] = data

    return jsonify(response), status_code


def error_response(message="操作失败", code="ERROR", details=None, status_code=400):
    """
    错误响应格式

    参数：
        message: 错误信息
        code: 错误代码
        details: 错误详情
        status_code: HTTP状态码
    """
    response = {
        "status": "error",
        "error": {
            "code": code,
            "message": message
        }
    }

    if details:
        response["error"]["details"] = details

    return jsonify(response), status_code


# ============================================================
# 用户管理API
# ============================================================

@app.route('/api/v1/users', methods=['GET'])
def get_users():
    """
    获取用户列表

    查询参数：
        page: 页码（默认1）
        limit: 每页数量（默认20）
        role: 角色过滤
        search: 搜索（姓名或邮箱）
        sort: 排序字段
        order: 排序顺序（asc/desc）
    """
    # 获取查询参数
    page = int(request.args.get('page', 1))
    limit = int(request.args.get('limit', 20))
    role = request.args.get('role')
    search = request.args.get('search')
    sort_field = request.args.get('sort', 'created_at')
    sort_order = request.args.get('order', 'desc')

    # 获取所有用户
    users_list = list(users_db.values())

    # 过滤
    if role:
        users_list = [u for u in users_list if u.get('role') == role]

    if search:
        users_list = [
            u for u in users_list
            if search.lower() in u.get('name', '').lower()
            or search.lower() in u.get('email', '').lower()
        ]

    # 排序
    reverse = (sort_order == 'desc')
    users_list.sort(key=lambda x: x.get(sort_field, ''), reverse=reverse)

    # 分页
    total = len(users_list)
    start = (page - 1) * limit
    end = start + limit
    users_page = users_list[start:end]

    # 构造响应
    response_data = {
        "users": users_page,
        "pagination": {
            "total": total,
            "page": page,
            "limit": limit,
            "pages": (total + limit - 1) // limit
        }
    }

    return success_response(response_data, "获取用户列表成功")


@app.route('/api/v1/users/<user_id>', methods=['GET'])
def get_user(user_id):
    """
    获取指定用户

    路径参数：
        user_id: 用户ID
    """
    user = users_db.get(user_id)

    if not user:
        return error_response(
            message=f"用户不存在",
            code="USER_NOT_FOUND",
            status_code=404
        )

    return success_response(user, "获取用户成功")


@app.route('/api/v1/users', methods=['POST'])
def create_user():
    """
    创建新用户

    请求体：
        {
            "name": "用户名",
            "email": "邮箱",
            "role": "角色"
        }
    """
    data = request.get_json()

    # 验证必填字段
    required_fields = ['name', 'email']
    missing_fields = [f for f in required_fields if f not in data]

    if missing_fields:
        return error_response(
            message="缺少必填字段",
            code="VALIDATION_ERROR",
            details=[{"field": f, "message": "此字段为必填项"} for f in missing_fields],
            status_code=422
        )

    # 验证邮箱唯一性
    email = data.get('email')
    if any(u['email'] == email for u in users_db.values()):
        return error_response(
            message="邮箱已存在",
            code="EMAIL_EXISTS",
            status_code=409
        )

    # 创建用户
    user_id = str(uuid.uuid4())
    user = {
        "id": user_id,
        "name": data['name'],
        "email": data['email'],
        "role": data.get('role', 'user'),
        "created_at": datetime.now().isoformat(),
        "updated_at": datetime.now().isoformat()
    }

    users_db[user_id] = user

    return success_response(user, "创建用户成功", 201)


@app.route('/api/v1/users/<user_id>', methods=['PUT'])
def update_user(user_id):
    """
    完整更新用户

    路径参数：
        user_id: 用户ID

    请求体：
        {
            "name": "用户名",
            "email": "邮箱",
            "role": "角色"
        }
    """
    if user_id not in users_db:
        return error_response(
            message="用户不存在",
            code="USER_NOT_FOUND",
            status_code=404
        )

    data = request.get_json()

    # 验证必填字段
    required_fields = ['name', 'email']
    missing_fields = [f for f in required_fields if f not in data]

    if missing_fields:
        return error_response(
            message="缺少必填字段",
            code="VALIDATION_ERROR",
            details=[{"field": f, "message": "此字段为必填项"} for f in missing_fields],
            status_code=422
        )

    # 更新用户
    users_db[user_id].update({
        "name": data['name'],
        "email": data['email'],
        "role": data.get('role', 'user'),
        "updated_at": datetime.now().isoformat()
    })

    return success_response(users_db[user_id], "更新用户成功")


@app.route('/api/v1/users/<user_id>', methods=['PATCH'])
def patch_user(user_id):
    """
    部分更新用户

    路径参数：
        user_id: 用户ID

    请求体：可以只包含要更新的字段
        {
            "name": "新用户名"
        }
    """
    if user_id not in users_db:
        return error_response(
            message="用户不存在",
            code="USER_NOT_FOUND",
            status_code=404
        )

    data = request.get_json()

    # 只更新提供的字段
    allowed_fields = ['name', 'email', 'role']
    for field in allowed_fields:
        if field in data:
            users_db[user_id][field] = data[field]

    users_db[user_id]['updated_at'] = datetime.now().isoformat()

    return success_response(users_db[user_id], "更新用户成功")


@app.route('/api/v1/users/<user_id>', methods=['DELETE'])
def delete_user(user_id):
    """
    删除用户

    路径参数：
        user_id: 用户ID
    """
    if user_id not in users_db:
        return error_response(
            message="用户不存在",
            code="USER_NOT_FOUND",
            status_code=404
        )

    del users_db[user_id]

    # DELETE成功通常返回204 No Content
    return '', 204


# ============================================================
# API文档和健康检查
# ============================================================

@app.route('/api/v1/health', methods=['GET'])
def health_check():
    """健康检查"""
    return success_response({
        "status": "healthy",
        "timestamp": datetime.now().isoformat()
    })


@app.route('/api/v1/docs', methods=['GET'])
def api_docs():
    """API文档"""
    docs = {
        "version": "1.0.0",
        "title": "用户管理API",
        "endpoints": [
            {
                "path": "/api/v1/users",
                "method": "GET",
                "description": "获取用户列表",
                "parameters": {
                    "page": "页码",
                    "limit": "每页数量",
                    "role": "角色过滤",
                    "search": "搜索",
                    "sort": "排序字段",
                    "order": "排序顺序"
                }
            },
            {
                "path": "/api/v1/users/<id>",
                "method": "GET",
                "description": "获取指定用户"
            },
            {
                "path": "/api/v1/users",
                "method": "POST",
                "description": "创建新用户",
                "body": {
                    "name": "用户名（必填）",
                    "email": "邮箱（必填）",
                    "role": "角色（可选）"
                }
            },
            {
                "path": "/api/v1/users/<id>",
                "method": "PUT",
                "description": "完整更新用户"
            },
            {
                "path": "/api/v1/users/<id>",
                "method": "PATCH",
                "description": "部分更新用户"
            },
            {
                "path": "/api/v1/users/<id>",
                "method": "DELETE",
                "description": "删除用户"
            }
        ]
    }

    return success_response(docs)


if __name__ == '__main__':
    print("""
    ╔══════════════════════════════════════════════════════════╗
    ║       RESTful API 服务器                                  ║
    ║       User Management API                                ║
    ╚══════════════════════════════════════════════════════════╝

    API地址: http://127.0.0.1:5000/api/v1

    可用端点:
    - GET    /api/v1/users          获取用户列表
    - GET    /api/v1/users/<id>     获取指定用户
    - POST   /api/v1/users          创建新用户
    - PUT    /api/v1/users/<id>     更新用户（完整）
    - PATCH  /api/v1/users/<id>     更新用户（部分）
    - DELETE /api/v1/users/<id>     删除用户
    - GET    /api/v1/health         健康检查
    - GET    /api/v1/docs           API文档

    测试命令:
    # 获取所有用户
    curl http://127.0.0.1:5000/api/v1/users

    # 创建用户
    curl -X POST http://127.0.0.1:5000/api/v1/users \\
      -H "Content-Type: application/json" \\
      -d '{"name":"测试用户","email":"test@example.com"}'

    # 获取单个用户
    curl http://127.0.0.1:5000/api/v1/users/<user_id>

    # 更新用户
    curl -X PATCH http://127.0.0.1:5000/api/v1/users/<user_id> \\
      -H "Content-Type: application/json" \\
      -d '{"name":"新名字"}'

    # 删除用户
    curl -X DELETE http://127.0.0.1:5000/api/v1/users/<user_id>
    """)

    app.run(debug=True, host='0.0.0.0', port=5000)

# 1. 获取所有用户
curl http://127.0.0.1:5000/api/v1/users

# 2. 分页和过滤
curl "http://127.0.0.1:5000/api/v1/users?page=1&limit=10&role=admin"

# 3. 创建用户
curl -X POST http://127.0.0.1:5000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "新用户",
    "email": "new@example.com",
    "role": "user"
  }'

# 4. 获取单个用户
curl http://127.0.0.1:5000/api/v1/users/<user_id>

# 5. 更新用户（PUT - 完整更新）
curl -X PUT http://127.0.0.1:5000/api/v1/users/<user_id> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "更新的用户",
    "email": "updated@example.com",
    "role": "admin"
  }'

# 6. 更新用户（PATCH - 部分更新）
curl -X PATCH http://127.0.0.1:5000/api/v1/users/<user_id> \
  -H "Content-Type: application/json" \
  -d '{"name": "只更新名字"}'

# 7. 删除用户
curl -X DELETE http://127.0.0.1:5000/api/v1/users/<user_id>

# 8. 健康检查
curl http://127.0.0.1:5000/api/v1/health