Module api_version 

API 版本管理 — URL/Header/Query 多策略

设计目标

提供灵活的 API 版本协商机制，支持三种主流策略：

1. URL 路径策略：/api/v1/users、/api/v2/users

   • 对齐 GitHub API、Twitter API 风格
   • 版本号作为 URL 路径前缀

2. Header 策略：

   • 自定义头 X-API-Version: 2
   • 或 Accept: application/vnd.api+json; version=2
   • 对齐 Stripe API、GitHub API（Accept header）风格

3. Query 参数策略：/api/users?api_version=2

   • 对齐部分内部 API 风格
   • 适合调试（浏览器直接访问）

中间件集成

ApiVersionExtractor 是 axum 中间件，从请求中提取版本号并注入到请求扩展中。 后续 handler 可通过 Request::extensions 获取 ApiVersion。

路由分组

VersionedRouter 提供按版本分组的路由构建器：

use sz_rust_core::api_version::{VersionedRouter, ApiVersion};

let router = VersionedRouter::new()
    .route("v1", "/users", axum::routing::get(get_users_v1))
    .route("v2", "/users", axum::routing::get(get_users_v2))
    .build();

默认版本与降级

• 未指定版本时使用 default_version（通常为最新稳定版）
• 不存在的版本返回 400 Bad Request（避免误用）

Structs

ApiVersion

API 版本号

ApiVersionExtractor

版本协商中间件状态

VersionNegotiator

版本协商器

VersionedRouter

版本化路由构建器

Enums

VersionError

版本协商错误

VersionStrategy

版本协商策略

Functions

version_negotiation_middleware

版本协商中间件