FastAPI 如何处理不同版本的 API？

推荐答案

在 FastAPI 中处理不同版本的 API 可以通过以下几种方式实现：

1. URL 路径版本控制：

   • 在 URL 路径中包含版本号，例如 /v1/items 和 /v2/items。
   • 这种方式简单直观，易于理解和实现。

   // www.javascriptcn.com code example
   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.get("/v1/items")
   def read_items_v1():
       return {"version": "v1"}
   
   @app.get("/v2/items")
   def read_items_v2():
       return {"version": "v2"}

2. 查询参数版本控制：

   • 在查询参数中包含版本号，例如 /items?version=v1 和 /items?version=v2。
   • 这种方式适用于需要向后兼容的场景。

   // www.javascriptcn.com code example
   from fastapi import FastAPI, Query
   
   app = FastAPI()
   
   @app.get("/items")
   def read_items(version: str = Query(...)):
       if version == "v1":
           return {"version": "v1"}
       elif version == "v2":
           return {"version": "v2"}

3. 请求头版本控制：

   • 在请求头中包含版本号，例如 X-API-Version: v1 和 X-API-Version: v2。
   • 这种方式适用于需要隐藏版本号的场景。

   // www.javascriptcn.com code example
   from fastapi import FastAPI, Header
   
   app = FastAPI()
   
   @app.get("/items")
   def read_items(x_api_version: str = Header(...)):
       if x_api_version == "v1":
           return {"version": "v1"}
       elif x_api_version == "v2":
           return {"version": "v2"}

4. 自定义路由版本控制：

   • 使用自定义路由来处理不同版本的 API。
   • 这种方式适用于需要更复杂版本控制的场景。

   // www.javascriptcn.com code example
   from fastapi import FastAPI, APIRouter
   
   app = FastAPI()
   
   v1_router = APIRouter(prefix="/v1")
   v2_router = APIRouter(prefix="/v2")
   
   @v1_router.get("/items")
   def read_items_v1():
       return {"version": "v1"}
   
   @v2_router.get("/items")
   def read_items_v2():
       return {"version": "v2"}
   
   app.include_router(v1_router)
   app.include_router(v2_router)

本题详细解读

URL 路径版本控制

• 优点：简单直观，易于理解和实现。
• 缺点：URL 路径中包含版本号可能会影响 URL 的美观性。

查询参数版本控制

• 优点：适用于需要向后兼容的场景。
• 缺点：查询参数可能会被忽略或误用。

请求头版本控制

• 优点：适用于需要隐藏版本号的场景。
• 缺点：需要客户端显式设置请求头。

自定义路由版本控制

• 优点：适用于需要更复杂版本控制的场景。
• 缺点：实现相对复杂，需要更多的代码量。

在实际开发中，选择哪种版本控制方式取决于具体的业务需求和团队约定。通常，URL 路径版本控制和自定义路由版本控制是最常用的方式。