FastAPI通用签名校验模块设计文档

作者: 源滚滚AI编程

创建时间: 2025年07月08日

版本: v1.0.0

文档状态: 设计阶段

版权声明

本文档由源滚滚AI编程创作，版权所有。未经作者书面许可，不得复制、分发或用于商业用途。

免责声明

本文档仅用于技术交流和学习目的。作者不对使用本文档内容导致的任何问题承担责任。在实际项目中应用时，请根据具体需求进行适当调整和测试。

1. 项目概述

1.1 项目目标

开发一套基于FastAPI的独立签名校验模块，支持pip安装，提供安全可靠的API接口签名验证机制，确保接口调用的合法性和数据完整性。该模块可被其他FastAPI项目快速集成使用，与登录认证模块解耦。

1.2 核心特性

多语言客户端支持（Python、JavaScript、PHP、Java、Golang、Rust）

基于app_key和app_secret的认证机制

请求参数签名校验

时间戳防重放攻击

数据库存储应用凭证

签名算法标准化

安全日志记录

可配置的签名策略

独立部署，与登录模块解耦

1.3 模块定位

独立模块: 专注于API签名校验，不包含用户登录认证

可插拔: 支持在现有FastAPI项目中快速集成

标准化: 提供统一的签名算法和验证流程

高性能: 优化的签名验证性能，支持高并发场景

2. 技术架构设计

2.1 技术栈选择

Web框架: FastAPI - 高性能、自动API文档生成

ORM: SQLAlchemy - 强大的数据库抽象层

数据库: 支持PostgreSQL、MySQL、SQLite

缓存: Redis (可选) - 提高签名验证性能

依赖注入: FastAPI内置依赖系统

2.2 模块架构

fastapi_signature/

├── core/                 # 核心配置和工具

│   ├── config.py        # 配置管理

│   ├── database.py      # 数据库连接

│   ├── cache.py         # 缓存管理

│   └── response.py      # 统一响应处理

├── models/              # 数据模型

│   ├── app_credentials.py  # 应用凭证模型

│   ├── signature_logs.py   # 签名日志模型

│   ├── signature_policies.py  # 签名策略模型

│   └── base.py          # 基础模型

├── schemas/             # Pydantic模型

│   ├── app_credentials.py  # 应用凭证Schema

│   ├── signature_logs.py   # 签名日志Schema

│   └── signature_policies.py  # 签名策略Schema

├── middleware/          # 中间件

│   └── signature.py     # 签名校验中间件

├── services/            # 业务逻辑层

│   ├── signature_service.py  # 签名服务

│   ├── app_service.py   # 应用管理服务

│   ├── policy_service.py  # 策略管理服务

│   └── log_service.py   # 日志服务

├── api/                 # API路由

│   ├── apps.py          # 应用管理API

│   ├── policies.py      # 策略管理API

│   ├── logs.py          # 日志查询API

│   └── tools.py         # 工具API

├── utils/               # 工具函数

│   ├── signature.py     # 签名生成和验证

│   ├── crypto.py        # 加密工具

│   └── validators.py    # 验证工具

└── dependencies/        # 依赖注入

  └── signature.py     # 签名依赖

3. 数据模型设计

3.1 应用凭证模型 (AppCredentials)

基础字段: id, app_key, app_secret, app_name, app_description

状态字段: status, created_at, updated_at

安全字段: ip_whitelist, rate_limit, created_by

用途: 存储应用的基本信息和认证凭证

3.2 签名日志模型 (SignatureLogs)

基础字段: id, app_key, request_id, request_url, request_method

参数字段: request_params, client_ip, user_agent

验证字段: signature, expected_signature, verification_result

性能字段: response_time, created_at

用途: 记录所有签名验证的详细日志

3.3 签名策略模型 (SignaturePolicies)

配置字段: id, policy_name, hash_method, case_sensitive

时间字段: timestamp_window, created_at, updated_at

策略字段: param_excludes, is_default, status

用途: 管理不同的签名算法和验证策略

4. 签名算法设计

4.1 签名生成流程

参数收集: 收集所有请求参数（除sign外）

参数排序: 按参数名ASCII码升序排列

参数拼接: 格式化为key=value&key=value

添加密钥: 在字符串末尾添加app_secret

哈希计算: 使用MD5/SHA256计算哈希值

大小写转换: 转换为大写或小写（可配置）

4.2 签名算法公式

sign = hash_method(querystring + "&app_secret=" + app_secret)

4.3 参数处理规则

必填参数: app_key, timestamp, sign

可选参数: 业务相关参数

排除参数: sign本身不参与签名计算

空值处理: 空字符串和null值统一处理

编码处理: URL编码处理特殊字符

4.4 时间戳防重放

时间窗口: 默认5分钟，可配置

时间格式: Unix时间戳（秒）

校验逻辑: |当前时间 - 请求时间| ≤ 时间窗口

时区处理: 统一使用UTC时间

5. 中间件实现

5.1 签名校验中间件

功能: 统一处理所有API请求的签名验证

流程: 参数提取 应用验证 签名验证 日志记录

性能: 支持缓存优化，减少数据库查询

错误处理: 统一的错误响应格式

5.2 中间件配置

启用/禁用: 可配置是否启用签名验证

路径过滤: 支持特定路径跳过签名验证

策略选择: 支持不同API使用不同签名策略

日志级别: 可配置日志记录详细程度

6. 安全设计

6.1 应用凭证安全

app_secret加密存储

支持密钥定期轮换

IP白名单限制

请求频率限制

6.2 签名算法安全

支持多种哈希算法

防重放攻击机制

参数完整性校验

时间窗口控制

6.3 日志安全

敏感信息脱敏

日志访问权限控制

日志数据加密存储

定期日志清理

7. 性能优化

7.1 缓存策略

应用凭证缓存

签名策略缓存

验证结果缓存

分布式缓存支持

7.2 数据库优化

索引优化

查询优化

连接池管理

读写分离支持

7.3 并发处理

异步处理

线程池管理

请求队列优化

负载均衡支持

8. 配置管理

8.1 核心配置项

数据库连接配置

缓存配置

签名算法配置

日志配置

安全配置

8.2 环境配置

开发环境配置

测试环境配置

生产环境配置

容器化配置

9. 部署方案

9.1 独立部署

作为独立的FastAPI应用部署

提供签名验证服务

支持负载均衡

容器化部署支持

9.2 集成部署

作为模块集成到现有FastAPI项目

通过pip安装使用

配置化启用/禁用

插件化架构

10. 监控和运维

10.1 监控指标

签名验证成功率

响应时间统计

错误率监控

并发量统计

10.2 告警机制

验证失败告警

性能异常告警

安全事件告警

系统故障告警

10.3 运维工具

健康检查接口

性能分析工具

日志分析工具

配置管理工具