Skill API命名规则最佳实践：从混乱到规范化的演进之路

1次阅读

共计 1924 个字符，预计需要花费 5 分钟才能阅读完成。

在团队协作开发 Skill API 时，糟糕的命名规则往往会引发一系列问题：

版本兼容性破坏 ：随意修改的 URI 导致客户端频繁报 404 错误（如从/getSkill 改为/querySkill）
文档自动化失败 ：Swagger 无法正确合并大小写不一致的路径（如/Skills 和/skills被识别为两个接口）
调试效率低下：查询参数命名歧义（如skillId vs id）迫使开发者反复查阅文档
缓存失效 ：URL 中包含随机大小写（如/Skills/123 和/skills/123）造成 CDN 缓存冗余

风格类型	核心约束	适用场景
RESTful	资源导向 +HTTP 动词语义化	资源 CRUD 为主的简单场景
GraphQL	操作类型（query/mutation）前缀	复杂数据聚合查询
RPC	动词直接暴露（如`activateSkill`）	需要明确动作语义的接口

资源命名标准化
使用复数名词：/skills 而非 /skill
二级资源使用嵌套：/skills/{id}/subskills
动作语义化表达
激活技能：POST /skills/{id}/activate
批量删除：DELETE /skills?ids=1,2,3
版本控制策略
URL Path：/v1/skills（适合重大变更）
Header：Accept: application/vnd.company.v1+json（兼容性更强）
查询参数规范
分页：?page=1&size=20
过滤：?type=programming&level=advanced

@RestController
@RequestMapping("/v1/skills")
@Tag(name = "Skill Management") // Swagger 注解
public class SkillController {@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
    public Page<Skill> listSkills(@Parameter(description="Filter by skill type") 
        @RequestParam(required = false) String type,
        @Parameter(description="Page number") 
        @RequestParam(defaultValue = "0") int page) {// 实现逻辑}

    @PostMapping("/{id}/activate")
    public ResponseEntity<Void> activateSkill(@Parameter(description="Skill ID") 
        @PathVariable String id) {// 实现逻辑}
}

from fastapi import APIRouter, Path, Query

router = APIRouter(prefix="/v1/skills", tags=["Skill Management"])

@router.get("/")
async def list_skills(type: str = Query(None, description="Filter by skill type"),
    page: int = Query(0, description="Page number")
):
    # 实现逻辑

@router.post("/{id}/activate")
async def activate_skill(id: str = Path(..., description="Skill ID")
):
    # 实现逻辑