后端编码

后端编码

本技能是流程指引，不是逐条打勾清单：按场景判断使用，遇不适用情况保持裁量，不机械执行。

API 设计规范

RESTful 规范

原则	说明
资源命名	使用名词复数表示资源
层级结构	使用嵌套表示资源关系
HTTP 方法	正确使用 GET/POST/PUT/PATCH/DELETE
统一接口	所有 API 遵循统一的接口约束
无状态	请求包含所有必要信息

HTTP 方法

方法	用途	幂等性	安全性	示例
GET	查询资源	幂等	安全	GET /users/123
POST	创建资源	非幂等	不安全	POST /users
PUT	更新资源（全量）	幂等	不安全	PUT /users/123
PATCH	更新资源（部分）	非幂等	不安全	PATCH /users/123
DELETE	删除资源	幂等	不安全	DELETE /users/123

URL 设计

规范	正确	错误
使用名词复数	GET /users	GET /getUsers
层级表示关系	GET /users/123/orders	GET /getUserOrders?userId=123
小写字母	GET /user-profiles	GET /UserProfiles
省略扩展名	GET /users/123	GET /users/123.json
查询参数过滤	GET /users?role=admin	GET /adminUsers

版本控制

URL 路径版本（推荐）：/v1/users, /v2/users

方式	示例	适用场景
URL 路径	/v1/users, /v2/users	简单直观，推荐
Header	API-Version: v1	资源导向
Query 参数	/users?version=v1	不推荐

FastAPI 最佳实践（本仓后端技术栈）

from fastapi import FastAPI, HTTPException, status, Query
from pydantic import BaseModel, EmailStr, Field
from typing import Optional, List

app = FastAPI(title="My API", version="1.0.0")

# 请求模型
class UserCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr
    role: str = Field(default="user")

# 响应模型
class UserResponse(BaseModel):
    id: int
    name: str
    email: EmailStr
    role: str

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int = Path(..., gt=0)) -> UserResponse:
    user = await db.get_user(user_id)
    if not user:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"User with id {user_id} not found")
    return user

@app.get("/users", response_model=List[UserResponse])
async def list_users(
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=100),
    role: Optional[str] = None
) -> List[UserResponse]:
    return await db.list_users(skip=skip, limit=limit, role=role)

@app.post("/users", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(user: UserCreate) -> UserResponse:
    existing = await db.get_user_by_email(user.email)
    if existing:
        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="User with this email already exists")
    return await db.create_user(user)