Python 银行示例 接口文档

#Python #银行示例 #接口文档

以下展示如何使用 curl 工具调用之前提供的 FastAPI 后端接口（main.py）来执行银行业务系统的增删改查操作。接口运行在 http://localhost:8000，以下示例涵盖客户（Customers）、账户（Accounts）和交易（Transactions）的常见操作，包括分页查询、搜索等功能。每个示例都包括请求和可能的响应。

1. 客户（Customers）接口示例

1.1 创建客户（POST /customers/）

请求：

curl -X POST "http://localhost:8000/customers/" \
-H "Content-Type: application/json" \
-d '{
    "first_name": "张",
    "last_name": "伟",
    "email": "zhang.wei@example.com",
    "phone": "13812345678",
    "address": "北京市朝阳区幸福路1号",
    "date_of_birth": "1985-05-20"
}'

响应（成功）：

{
    "customer_id": 1,
    "first_name": "张",
    "last_name": "伟",
    "email": "zhang.wei@example.com",
    "phone": "13812345678",
    "address": "北京市朝阳区幸福路1号",
    "date_of_birth": "1985-05-20",
    "created_at": "2025-07-15T12:30:00.123456"
}

1.2 查询客户列表（GET /customers/，支持分页和搜索）

请求（分页：第1页，每页10条，搜索“张”）：

curl -X GET "http://localhost:8000/customers/?page=1&per_page=10&search=张"

响应（成功，返回匹配的客户列表）：

[
    {
        "customer_id": 1,
        "first_name": "张",
        "last_name": "伟",
        "email": "zhang.wei@example.com",
        "phone": "13812345678",
        "address": "北京市朝阳区幸福路1号",
        "date_of_birth": "1985-05-20",
        "created_at": "2025-07-15T12:30:00.123456"
    }
]

1.3 获取单个客户（GET /customers/{id}）

请求：

curl -X GET "http://localhost:8000/customers/1"

响应（成功）：

{
    "customer_id": 1,
    "first_name": "张",
    "last_name": "伟",
    "email": "zhang.wei@example.com",
    "phone": "13812345678",
    "address": "北京市朝阳区幸福路1号",
    "date_of_birth": "1985-05-20",
    "created_at": "2025-07-15T12:30:00.123456"
}

响应（失败，客户不存在）：

{
    "detail": "客户未找到"
}

1.4 更新客户（PUT /customers/{id}）

请求：

curl -X PUT "http://localhost:8000/customers/1" \
-H "Content-Type: application/json" \
-d '{
    "first_name": "张",
    "last_name": "伟",
    "email": "zhang.wei2@example.com",
    "phone": "13987654321",
    "address": "北京市海淀区幸福路2号",
    "date_of_birth": "1985-05-20"
}'

响应（成功）：

{
    "customer_id": 1,
    "first_name": "张",
    "last_name": "伟",
    "email": "zhang.wei2@example.com",
    "phone": "13987654321",
    "address": "北京市海淀区幸福路2号",
    "date_of_birth": "1985-05-20",
    "created_at": "2025-07-15T12:30:00.123456"
}

1.5 删除客户（DELETE /customers/{id}）

请求：

curl -X DELETE "http://localhost:8000/customers/1"

响应（成功）：

{
    "message": "客户已删除"
}

2. 账户（Accounts）接口示例

2.1 创建账户（POST /accounts/）

请求：

curl -X POST "http://localhost:8000/accounts/" \
-H "Content-Type: application/json" \
-d '{
    "customer_id": 1,
    "branch_id": 1,
    "account_type": "savings",
    "balance": 1000.00
}'

响应（成功）：

{
    "account_id": 1,
    "customer_id": 1,
    "branch_id": 1,
    "account_type": "savings",
    "balance": 1000.00,
    "created_at": "2025-07-15T12:30:00.123456"
}

2.2 查询账户列表（GET /accounts/，支持分页和搜索）

请求（分页：第1页，每页10条，搜索“savings”）：

curl -X GET "http://localhost:8000/accounts/?page=1&per_page=10&search=savings"

响应（成功）：

[
    {
        "account_id": 1,
        "customer_id": 1,
        "branch_id": 1,
        "account_type": "savings",
        "balance": 1000.00,
        "created_at": "2025-07-15T12:30:00.123456"
    }
]

3. 交易（Transactions）接口示例

3.1 创建交易（POST /transactions/）

请求：

curl -X POST "http://localhost:8000/transactions/" \
-H "Content-Type: application/json" \
-d '{
    "account_id": 1,
    "transaction_type": "deposit",
    "amount": 500.00,
    "description": "存款"
}'

响应（成功）：

{
    "transaction_id": 1,
    "account_id": 1,
    "transaction_type": "deposit",
    "amount": 500.00,
    "description": "存款",
    "transaction_date": "2025-07-15T12:30:00.123456"
}

3.2 查询交易列表（GET /transactions/，支持分页和搜索）

请求（分页：第1页，每页10条，搜索“deposit”）：

curl -X GET "http://localhost:8000/transactions/?page=1&per_page=10&search=deposit"

响应（成功）：

[
    {
        "transaction_id": 1,
        "account_id": 1,
        "transaction_type": "deposit",
        "amount": 500.00,
        "description": "存款",
        "transaction_date": "2025-07-15T12:30:00.123456"
    }
]

使用说明

  1. 前提条件：

    • 确保 FastAPI 服务正在运行：
      uvicorn main:app --reload
    • 数据库已正确配置并包含数据（通过 generate_data.py 生成）。
    • 确保 main.py 中的数据库连接参数（dbname、user、password、host、port）正确。

  2. 注意事项：

    • 外键约束：创建账户或交易时，customer_id 和 branch_id 必须存在于 customers 和 branches 表中，否则会返回外键约束错误。
    • 唯一约束：创建客户时，email 必须唯一，否则会返回 409 Conflict 错误。
    • 分页和搜索：page 从 1 开始，per_page 控制每页记录数，search 参数支持模糊匹配。
    • 错误处理：如果资源不存在（如客户 ID 不存在），API 会返回 404 错误。

  3. 扩展：

    • 可以为其他表（如 branches、employees、loans、cards）添加类似 curl 示例。
    • 如果需要认证，需在 main.py 中添加 JWT 或其他认证机制，并在 curl 请求中添加 Authorization 头。

  4. 调试：

    • 如果请求失败，检查 FastAPI 的控制台输出或数据库日志。
    • 确保请求的 JSON 格式正确，避免语法错误。

示例扩展

如果需要为其他表（如 loans 或 cards）添加 curl 示例，或需要更复杂的查询（例如联合查询或过滤特定条件的交易），请告诉我，我可以提供进一步的代码或示例！