30 KiB
30 KiB
通用API规范
**本文引用的文件** - [CommonResult.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/CommonResult.java) - [PageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/PageParam.java) - [SortablePageParam.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortablePageParam.java) - [SortingField.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/pojo/SortingField.java) - [GlobalErrorCodeConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/exception/enums/GlobalErrorCodeConstants.java) - [RpcConstants.java](file://viewsh-framework/viewsh-common/src/main/java/com/viewsh/framework/common/enums/RpcConstants.java) - [WebProperties.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/config/WebProperties.java) - [WebFrameworkUtils.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/util/WebFrameworkUtils.java) - [ApiConstants.java（系统模块）](file://viewsh-module-system/viewsh-module-system-api/src/main/java/com/viewsh/module/system/enums/ApiConstants.java) - [ApiConstants.java（ops模块）](file://viewsh-module-ops/viewsh-module-ops-api/src/main/java/com/viewsh/module/ops/enums/ApiConstants.java) - [ApiAccessLog.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/annotation/APIAccessLog.java) - [ApiAccessLogFilter.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/apilog/core/filter/APIAccessLogFilter.java) - [Idempotent.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/annotation/Idempotent.java) - [IdempotentAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/idempotent/core/aop/IdempotentAspect.java) - [RateLimiter.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/annotation/RateLimiter.java) - [RateLimiterAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/aop/RateLimiterAspect.java) - [RateLimiterRedisDAO.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/ratelimiter/core/redis/RateLimiterRedisDAO.java) - [ApiSignature.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/annotation/ApiSignature.java) - [ApiSignatureAspect.java](file://viewsh-framework/viewsh-spring-boot-starter-protection/src/main/java/com/viewsh/framework/signature/core/aop/ApiSignatureAspect.java) - [OAuth2TokenServiceImpl.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/oauth2/OAuth2TokenServiceImpl.java) - [OAuth2AccessTokenRedisDAO.java](file://viewsh-module-system/viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/redis/oauth2/OAuth2AccessTokenRedisDAO.java) - [OAuth2OpenControllerTest.java](file://viewsh-module-system/viewsh-module-system-server/src/test/java/com/viewsh/module/system/controller/admin/oauth2/OAuth2OpenControllerTest.java) - [Knife4jOpenApiCustomizer.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/swagger/config/Knife4jOpenApiCustomizer.java) - [接口文档.md](file://docs/technical-overview/07-接口文档.md)目录
引言
本文件旨在为整个平台制定统一的API规范，覆盖响应格式、错误码、分页与排序、版本管理与兼容性、认证授权、限流与幂等、API文档生成与维护、测试与调试、以及安全防护等方面。规范以仓库现有实现为依据，确保跨模块一致性与可维护性。
项目结构
平台采用多模块架构，API规范涉及以下关键层次：
- 通用响应与异常：统一返回体、错误码、分页与排序模型
- 网关与路由：前缀与路由规则、RPC与HTTP区分
- 认证授权：OAuth2令牌生命周期与Redis存储
- 安全与防护：签名、限流、幂等
- 文档生成：Knife4j聚合与标签排序
graph TB
subgraph "通用层"
CR["CommonResult<br/>统一响应"]
EC["GlobalErrorCodeConstants<br/>全局错误码"]
PP["PageParam/SortablePageParam<br/>分页与排序"]
end
subgraph "网关与路由"
WP["WebProperties<br/>前缀配置"]
WFU["WebFrameworkUtils<br/>请求上下文/头解析"]
RC["RpcConstants<br/>RPC前缀"]
end
subgraph "认证授权"
OAT["OAuth2TokenServiceImpl<br/>令牌创建/刷新"]
OAR["OAuth2AccessTokenRedisDAO<br/>令牌Redis存储"]
end
subgraph "安全与防护"
SIG["ApiSignatureAspect<br/>请求签名"]
RL["RateLimiterAspect/DAO<br/>限流"]
IDP["IdempotentAspect<br/>幂等"]
end
subgraph "文档"
K4J["Knife4jOpenApiCustomizer<br/>文档聚合/排序"]
end
CR --> EC
PP --> CR
WP --> WFU
RC --> WP
OAT --> OAR
SIG --> CR
RL --> CR
IDP --> CR
K4J --> CR
图表来源
- CommonResult.java
- GlobalErrorCodeConstants.java
- PageParam.java
- SortablePageParam.java
- WebProperties.java
- WebFrameworkUtils.java
- RpcConstants.java
- OAuth2TokenServiceImpl.java
- OAuth2AccessTokenRedisDAO.java
- ApiSignatureAspect.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- IdempotentAspect.java
- Knife4jOpenApiCustomizer.java
章节来源
核心组件
- 统一响应体：所有HTTP接口返回统一结构，包含业务状态码、提示信息与数据载体
- 错误码体系：区分HTTP状态与业务错误码，覆盖客户端、服务端与自定义错误
- 分页与排序：标准化分页参数与排序字段，支持多字段排序
- 版本前缀与路由：RESTful URL按模块前缀划分，RPC接口走独立前缀
- 认证授权：OAuth2令牌创建与刷新，Redis存储访问令牌
- 安全与防护：签名验证、限流、幂等拦截
- 文档生成：Knife4j聚合与标签排序增强
章节来源
- CommonResult.java
- GlobalErrorCodeConstants.java
- PageParam.java
- SortablePageParam.java
- SortingField.java
- WebProperties.java
- RpcConstants.java
- OAuth2TokenServiceImpl.java
- OAuth2AccessTokenRedisDAO.java
- ApiSignatureAspect.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- IdempotentAspect.java
- Knife4jOpenApiCustomizer.java
架构总览
平台API遵循RESTful风格，HTTP状态码用于网络层，业务状态码用于业务层；通过前缀区分Admin与App接口，RPC接口走独立前缀；认证采用OAuth2，安全通过签名、限流与幂等保障；文档通过Knife4j聚合。
sequenceDiagram
participant C as "客户端"
participant G as "网关/Gateway"
participant S as "业务服务"
participant SEC as "安全组件"
participant DOC as "文档聚合"
C->>G : "HTTP 请求 (含前缀)"
G->>S : "路由转发"
S->>SEC : "鉴权/签名/限流/幂等"
SEC-->>S : "通过/拒绝"
S-->>C : "统一响应体 (code/msg/data)"
DOC-->>C : "Knife4j 聚合文档"
图表来源
章节来源
详细组件分析
统一响应与错误码
- 响应体字段
- code：业务错误码，0表示成功
- msg：错误提示信息
- data：业务数据
- 错误码范围
- 客户端错误：400、401、403、404、405、423、429
- 服务端错误：500、501、502
- 自定义错误：900、901、999
- 使用建议
- 成功返回使用统一成功码
- 异常抛出时使用全局错误码或业务错误码
classDiagram
class CommonResult {
+Integer code
+String msg
+T data
+isSuccess() boolean
+checkError() void
}
class GlobalErrorCodeConstants {
<<interface>>
+SUCCESS
+BAD_REQUEST
+UNAUTHORIZED
+FORBIDDEN
+NOT_FOUND
+METHOD_NOT_ALLOWED
+LOCKED
+TOO_MANY_REQUESTS
+INTERNAL_SERVER_ERROR
+NOT_IMPLEMENTED
+ERROR_CONFIGURATION
+REPEATED_REQUESTS
+DEMO_DENY
+UNKNOWN
}
CommonResult --> GlobalErrorCodeConstants : "使用"
图表来源
章节来源
分页与排序
- 分页参数
- pageNo：起始页（默认1，最小1）
- pageSize：每页数量（默认10，最大200；-1表示不分页导出）
- 排序参数
- 支持多字段排序，字段与顺序（asc/desc）
- 使用建议
- 导出场景使用-1不分页
- 接口文档中明确排序字段与顺序
classDiagram
class PageParam {
+Integer pageNo
+Integer pageSize
}
class SortablePageParam {
+SortingField[] sortingFields
}
class SortingField {
+String field
+String order
}
SortablePageParam --|> PageParam
SortablePageParam --> SortingField : "包含"
图表来源
章节来源
版本管理与路由
- RESTful版本前缀
- Admin接口：/admin-api/{module}/{resource}/v{version}
- App接口：/app-api/{module}/{resource}/v{version}
- RPC接口
- 统一前缀：/rpc-api/{service}
- 示例：/rpc-api/system
- 网关路由
- 根据前缀将请求转发至对应服务
- 版本号
- 各模块在ApiConstants中定义版本字符串，建议语义化版本
flowchart TD
A["请求路径"] --> B{"前缀判断"}
B --> |/admin-api/*| C["Admin服务"]
B --> |/app-api/*| D["App服务"]
B --> |/rpc-api/*| E["RPC服务"]
C --> F["模块路由"]
D --> F
E --> F
图表来源
章节来源
认证授权与令牌管理
- 令牌创建
- 通过OAuth2创建访问令牌与刷新令牌
- 令牌刷新
- 校验刷新令牌有效性、客户端匹配、过期时间
- 刷新成功后清理旧访问令牌
- 令牌存储
- 访问令牌使用Redis存储，便于快速校验与撤销
- 授权头
- Authorization: Bearer {token}
sequenceDiagram
participant C as "客户端"
participant S as "系统服务"
participant M as "令牌服务"
participant R as "Redis"
C->>S : "登录/换取令牌"
S->>M : "创建访问令牌"
M-->>S : "返回访问令牌"
S-->>C : "返回令牌"
C->>S : "携带Bearer Token访问受保护接口"
S->>R : "校验访问令牌"
R-->>S : "校验结果"
S-->>C : "业务响应"
C->>S : "刷新令牌"
S->>M : "校验并刷新"
M->>R : "清理旧令牌"
M-->>S : "新令牌"
S-->>C : "新令牌"
图表来源
章节来源
限流与幂等
- 限流
- 支持全局、用户、客户端IP、服务节点等维度
- 基于Redisson限流器实现，动态配置速率
- 幂等
- 基于注解与Redis实现，防止重复提交
- 默认超时窗口与提示信息可配置
flowchart TD
S["进入受保护接口"] --> RL["限流检查"]
RL --> |允许| IDP["幂等检查"]
RL --> |拒绝| ER["返回限流错误"]
IDP --> |通过| EXEC["执行业务逻辑"]
IDP --> |冲突| EIDP["返回重复请求错误"]
EXEC --> RET["返回统一响应"]
图表来源
- RateLimiter.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- Idempotent.java
- IdempotentAspect.java
章节来源
- RateLimiter.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- Idempotent.java
- IdempotentAspect.java
API文档生成与维护
- 生成与聚合
- 使用Knife4j（Swagger增强）自动生成与聚合微服务文档
- 统一入口：doc.html
- 标签排序
- 通过扩展为Tag添加x-order属性，实现文档侧边栏排序
- 开发注解
- 使用@Tag、@Operation、@Schema等标注接口与字段
graph LR
A["Controller"] --> B["@Tag/@Operation/@Schema"]
B --> C["Knife4j OpenAPI"]
C --> D["聚合文档 (doc.html)"]
图表来源
章节来源
安全与防护
- 请求签名
- 基于时间戳、随机数、参数排序与密钥计算签名，防重放与篡改
- 限流与幂等
- 已在上文详述
- 访问日志
- 可选的访问日志过滤器与注解，记录操作模块、名称与类型
章节来源
依赖关系分析
- 统一响应与错误码贯穿各模块，确保接口一致性
- 分页与排序模型被大量控制器使用，形成跨模块契约
- 网关前缀与RPC常量定义了清晰的路由边界
- 安全组件通过AOP织入，对业务透明
- 文档聚合依赖Knife4j与Tag注解
graph TB
CR["CommonResult"] --> EC["GlobalErrorCodeConstants"]
PP["PageParam/SortablePageParam"] --> CR
WP["WebProperties"] --> WFU["WebFrameworkUtils"]
RC["RpcConstants"] --> WP
OAT["OAuth2TokenServiceImpl"] --> OAR["OAuth2AccessTokenRedisDAO"]
SIG["ApiSignatureAspect"] --> CR
RL["RateLimiterAspect/DAO"] --> CR
IDP["IdempotentAspect"] --> CR
K4J["Knife4jOpenApiCustomizer"] --> CR
图表来源
- CommonResult.java
- GlobalErrorCodeConstants.java
- PageParam.java
- WebProperties.java
- WebFrameworkUtils.java
- RpcConstants.java
- OAuth2TokenServiceImpl.java
- OAuth2AccessTokenRedisDAO.java
- ApiSignatureAspect.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- IdempotentAspect.java
- Knife4jOpenApiCustomizer.java
章节来源
- CommonResult.java
- PageParam.java
- WebProperties.java
- RpcConstants.java
- OAuth2TokenServiceImpl.java
- OAuth2AccessTokenRedisDAO.java
- ApiSignatureAspect.java
- RateLimiterAspect.java
- RateLimiterRedisDAO.java
- IdempotentAspect.java
- Knife4jOpenApiCustomizer.java
性能考量
- 限流策略
- 建议按接口粒度配置不同阈值，结合用户/IP/节点维度
- 动态配置速率，避免硬编码
- 幂等设计
- 对写操作强制幂等，减少重试带来的副作用
- 缓存与存储
- 访问令牌使用Redis，降低数据库压力
- 文档生成
- 聚合文档仅在必要时刷新，避免频繁扫描
故障排查指南
- 统一响应与错误码
- 检查响应体中的code与msg，定位业务异常
- 使用全局错误码映射快速识别HTTP与业务错误
- 认证授权
- 确认Authorization头格式与令牌有效性
- 校验刷新令牌是否过期或客户端不匹配
- 限流与幂等
- 若频繁收到限流错误，调整限流配置或客户端退避
- 幂等冲突时，检查请求键与超时设置
- 文档与路由
- 确认请求前缀与目标服务匹配
- 通过Knife4j确认接口暴露情况
章节来源
- CommonResult.java
- GlobalErrorCodeConstants.java
- OAuth2TokenServiceImpl.java
- OAuth2AccessTokenRedisDAO.java
- RateLimiterAspect.java
- IdempotentAspect.java
- Knife4jOpenApiCustomizer.java
结论
本规范以现有实现为基础，明确了平台API的统一响应、错误码、分页排序、版本与路由、认证授权、限流与幂等、文档生成与维护、测试与调试以及安全防护要求。建议在后续迭代中持续完善各模块的版本号与路由前缀，强化安全组件的配置与监控，确保跨模块一致性与可维护性。
附录
- API测试最佳实践
- 使用HTTP客户端环境文件组织请求
- 针对认证、限流、幂等场景编写集成测试
- 调试工具
- Knife4j文档入口与接口调试
- 访问日志与错误日志辅助定位问题
章节来源