### 一、核心命名基础规则

这是所有接口必须遵循的底层约定，统一路径、方法、字段的基础标准，保证接口具备自解释能力。
1. URL 路径规范 

- 资源统一用名词复数表示集合，单体资源拼接 /{id}，如 /users、/users/123，禁止动词开头、单复数混用
- 多单词采用 kebab-case（短横线分隔）全小写格式，如 /user-orders
- 从属关系通过路径嵌套体现，层级不超过 3 级，如 /orders/{order_id}/items
- 全局统一前缀格式：/api/版本号/业务资源  

1. HTTP 方法语义  严格用 HTTP 方法对应业务动作，禁止全接口用 POST、用 GET 执行写操作： 

- GET：查询资源
- POST：新增资源
- PUT：全量更新资源
- PATCH：部分更新资源
- DELETE：删除资源  

1. 参数字段规范 

- 查询参数、请求 / 响应字段统一采用 snake_case 风格，与 Python 原生编码习惯一致
- 布尔字段统一加 is_/has_ 前缀，列表响应固定为 list + total 结构
- 禁用拼音、无意义自造缩写、中英文混合命名

### 二、场景化与兼容规范

针对非标准 CRUD 业务、接口迭代、异常响应等场景补充约定，覆盖全业务场景的命名一致性。
1. 特殊动作接口：对资源执行特定状态操作时，采用 POST /资源/{id}/动作名 格式，如 POST /users/123/disable、POST /orders/123/pay 
2. 批量操作：在集合资源下新增 batch-xxx 路径，如 POST /users/batch-delete
3. 版本控制：采用 URL 路径大版本方案，如 /api/v1/users、/api/v2/users，小功能迭代不升级版本号
4. 错误响应规范：HTTP 状态码精准对应错误类型；业务错误码按模块分段管理（通用 1xxxx、用户 2xxxx、订单 3xxxx），错误信息语义明确，禁止模糊提示

### 三、Python FastAPI 落地代码

**1. 接口路由定义**
```PYTHON
from fastapi import APIRouter, Query, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import Optional, List, Any

# ==================== 1. 统一返回结构 & DTO 定义 ====================

class Result(BaseModel):
    """统一响应结构"""
    code: int = 200
    message: str = "success"
    data: Optional[Any] = None

class PageResult(BaseModel):
    """分页响应结构"""
    list: List[Any] = []
    total: int = 0

class UserCreateDTO(BaseModel):
    """创建用户入参"""
    username: str = Field(..., min_length=3, max_length=20, description="用户名")
    email: str = Field(..., description="用户邮箱")
    password: str = Field(..., min_length=6, description="密码")

class UserUpdateDTO(BaseModel):
    """更新用户入参"""
    username: Optional[str] = None
    email: Optional[str] = None

class BatchDeleteDTO(BaseModel):
    """批量删除入参"""
    user_ids: List[int] = Field(..., description="待删除的用户ID列表")


# ==================== 2. 模拟 Service 层 (实际项目中应抽离到独立文件) ====================

class UserService:
    @staticmethod
    def list_users(page_num: int, page_size: int, keyword: Optional[str]):
        # TODO: 接入真实数据库查询逻辑
        return PageResult(list=[], total=0)

    @staticmethod
    def get_user_by_id(user_id: int):
        # TODO: 查询数据库，找不到时抛出异常
        return {"id": user_id, "username": "test"}

    @staticmethod
    def create_user(dto: UserCreateDTO):
        # TODO: 数据库插入逻辑
        pass

    @staticmethod
    def update_user(user_id: int, dto: UserUpdateDTO):
        # TODO: 数据库更新逻辑
        pass

    @staticmethod
    def delete_user(user_id: int):
        # TODO: 数据库删除逻辑
        pass

    @staticmethod
    def disable_user(user_id: int):
        # TODO: 状态变更逻辑
        pass

    @staticmethod
    def batch_delete_users(dto: BatchDeleteDTO):
        # TODO: 批量删除逻辑
        pass


# ==================== 3. 依赖注入 (鉴权示例) ====================

def get_current_user():
    """模拟获取当前登录用户的依赖注入"""
    # TODO: 解析 Token，校验权限
    return {"id": 1, "role": "admin"}


# ==================== 4. Router 控制器层 ====================

router = APIRouter(prefix="/users", tags=["用户管理"])

@router.get("", summary="查询用户列表")
def list_users(
    page_num: int = Query(1, ge=1, description="页码"),
    page_size: int = Query(10, ge=1, le=100, description="每页条数"),
    keyword: Optional[str] = Query(None, description="搜索关键词")
):
    data = UserService.list_users(page_num, page_size, keyword)
    return Result(data=data)

@router.get("/{user_id}", summary="查询单个用户")
def get_user(user_id: int):
    user = UserService.get_user_by_id(user_id)
    if not user:
        raise HTTPException(status_code=404, detail=f"用户 {user_id} 不存在")
    return Result(data=user)

@router.post("", summary="新增用户")
def create_user(body: UserCreateDTO, current_user=Depends(get_current_user)):
    UserService.create_user(body)
    return Result(message="创建成功")

@router.put("/{user_id}", summary="全量更新用户")
def update_user(user_id: int, body: UserUpdateDTO, current_user=Depends(get_current_user)):
    UserService.update_user(user_id, body)
    return Result(message="更新成功")

@router.delete("/{user_id}", summary="删除用户")
def delete_user(user_id: int, current_user=Depends(get_current_user)):
    UserService.delete_user(user_id)
    return Result(message="删除成功")

@router.post("/{user_id}/disable", summary="禁用用户")
def disable_user(user_id: int, current_user=Depends(get_current_user)):
    UserService.disable_user(user_id)
    return Result(message="禁用成功")

@router.post("/batch-delete", summary="批量删除用户")
def batch_delete_users(body: BatchDeleteDTO, current_user=Depends(get_current_user)):
    UserService.batch_delete_users(body)
    return Result(message="批量删除成功")
```

**2. 数据模型定义**
```python
from pydantic import BaseModel, Field
from typing import Generic, TypeVar, List, Optional

T = TypeVar("T")


class UserCreateDTO(BaseModel):
    username: str = Field(..., min_length=3, max_length=20)
    phone: str = Field(..., pattern=r"^1[3-9]\d{9}$")
    email: str = Field(..., description="用户邮箱")
    dept_id: int = Field(..., gt=0)
    is_enabled: bool = True


class UserUpdateDTO(BaseModel):
    username: Optional[str] = Field(None, min_length=3, max_length=20)
    phone: Optional[str] = Field(None, pattern=r"^1[3-9]\d{9}$")
    email: Optional[str] = None
    dept_id: Optional[int] = Field(None, gt=0)
    is_enabled: Optional[bool] = None


class BatchDeleteDTO(BaseModel):
    ids: List[int] = Field(..., min_length=1, description="待删除的用户ID列表")


class PageResult(BaseModel, Generic[T]):
    list: List[T] = []
    total: int = 0


class Result(BaseModel, Generic[T]):
    code: int = 200
    message: str = "success"
    data: Optional[T] = None
```
3. 错误码枚举
```python
from enum import IntEnum


class ErrorCode(IntEnum):
    PARAM_INVALID = 10001
    UNAUTHORIZED = 10002
    USER_NOT_EXIST = 20001
    USER_ALREADY_EXIST = 20002
    ORDER_NOT_EXIST = 30001


ERROR_MESSAGES: dict[ErrorCode, str] = {
    ErrorCode.PARAM_INVALID: "参数不合法",
    ErrorCode.UNAUTHORIZED: "未授权访问",
    ErrorCode.USER_NOT_EXIST: "用户不存在",
    ErrorCode.USER_ALREADY_EXIST: "用户名已存在",
    ErrorCode.ORDER_NOT_EXIST: "订单不存在",
}
```

这是所有接口必须遵循的底层约定，统一路径、方法、字段的基础标准，保证接口具备自解释能力。

API 接口命名规范

后端

架构设计

开发工具

RESTful API设计规范详解：包含URL路径、HTTP方法、参数字段命名规则，以及FastAPI实现代码示例。涵盖资源命名、批量操作、版本控制、错误响应等核心规范，提供Python代码落地实践，帮助开发者构建标准化的API接口。

数据库

路由

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

API 接口命名规范-腾讯云开发者社区-腾讯云

API 接口命名规范

API 接口命名规范

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐