SimpleBank API 接口详解与使用指南

SimpleBank API 接口详解与使用指南

simplebank Backend master class: build a simple bank service in Go 项目地址: https://gitcode.com/gh_mirrors/si/simplebank

项目概述

SimpleBank 是一个简洁高效的银行系统 API 项目，提供了用户管理、认证授权等核心功能。本文将从技术角度详细解析其 API 设计，帮助开发者快速理解和使用这套接口。

API 基础信息

SimpleBank API 遵循 RESTful 设计原则，使用 JSON 作为数据交换格式：

• 当前版本：1.2
• 请求/响应格式：application/json
• 认证方式：基于 Token 的认证机制

核心接口详解

1. 用户注册接口

端点：POST /v1/create_user

功能：创建新用户账户

请求参数：

{
  "username": "string",
  "fullName": "string",
  "email": "string",
  "password": "string"
}

响应示例：

{
  "user": {
    "username": "string",
    "fullName": "string",
    "email": "string",
    "passwordChangedAt": "date-time",
    "createdAt": "date-time"
  }
}

技术要点：

• 密码应采用加密存储，推荐使用 bcrypt 等安全哈希算法
• 创建用户时应验证用户名和邮箱的唯一性
• 建议实现密码强度验证策略

2. 用户登录接口

端点：POST /v1/login_user

功能：用户认证并获取访问令牌

请求参数：

{
  "username": "string",
  "password": "string"
}

响应示例：

{
  "user": {
    "username": "string",
    "fullName": "string",
    "email": "string",
    "passwordChangedAt": "date-time",
    "createdAt": "date-time"
  },
  "sessionId": "string",
  "accessToken": "string",
  "refreshToken": "string",
  "accessTokenExpiresAt": "date-time",
  "refreshTokenExpiresAt": "date-time"
}

技术要点：

• 实现了双 Token 机制（Access Token + Refresh Token）
• Access Token 应设置较短的有效期（如15分钟）
• Refresh Token 有效期较长（如7天），用于获取新的 Access Token
• 推荐使用 JWT 作为 Token 实现方案

3. 用户信息更新接口

端点：PATCH /v1/update_user

功能：更新用户个人信息

请求参数：

{
  "username": "string",
  "fullName": "string",
  "email": "string",
  "password": "string"
}

响应示例：

{
  "user": {
    "username": "string",
    "fullName": "string",
    "email": "string",
    "passwordChangedAt": "date-time",
    "createdAt": "date-time"
  }
}

技术要点：

• 使用 PATCH 而非 PUT，支持部分字段更新
• 密码变更后应更新 passwordChangedAt 时间戳
• 应验证当前用户权限，确保只能修改自己的信息

4. 邮箱验证接口

端点：GET /v1/verify_email

功能：验证用户邮箱地址

查询参数：

• emailId: string (int64格式)
• secretCode: string

响应示例：

{
  "isVerified": true
}

技术要点：

• 应采用一次性验证码机制
• 验证链接应有时效性（如24小时内有效）
• 验证成功后应标记用户邮箱为已验证状态

数据模型定义

用户模型 (pbUser)

{
  "username": "string",
  "fullName": "string",
  "email": "string",
  "passwordChangedAt": "date-time",
  "createdAt": "date-time"
}

错误响应模型 (rpcStatus)

{
  "code": "integer",
  "message": "string",
  "details": [
    {
      "@type": "string",
      // 其他属性
    }
  ]
}

最佳实践建议

1. 安全建议：

   • 所有 API 请求应通过 HTTPS
   • 敏感接口应实施速率限制
   • 密码字段应永远不在响应中返回

2. 性能优化：

   • 对频繁访问的接口添加缓存层
   • 考虑实现接口版本控制

3. 扩展性考虑：

   • 可添加用户角色和权限管理
   • 未来可扩展账户、交易等金融相关功能

常见问题解答

Q: 如何处理 Token 过期？ A: 客户端应使用 Refresh Token 获取新的 Access Token，当 Refresh Token 也过期时，需要用户重新登录。

Q: 密码重置功能如何实现？ A: 可通过发送包含重置链接的邮件实现，类似邮箱验证流程，但需要额外的安全验证。

Q: 如何确保接口幂等性？ A: 对于创建类操作，可使用唯一约束；对于更新类操作，可使用条件更新或乐观锁。

通过本文的详细解析，开发者应该能够全面理解 SimpleBank API 的设计理念和使用方法。这套接口设计简洁但功能完备，非常适合作为学习 RESTful API 设计和实现的参考案例。

simplebank Backend master class: build a simple bank service in Go 项目地址: https://gitcode.com/gh_mirrors/si/simplebank