编码和接口设计规范

1. 编码规范

• 遵循 Google 开源项目风格指南，确保代码的可读性和一致性
• 接口参数以及路径必须进行注释或描述如下：
  • @public.post("/gitlab/", summary='将gitlab仓库提交信息推送到飞书') async def gitlab_pop(requests: Request, data=Body(description='gitlab推送信息')): pass

1. 接口命名和路由设计

• 根据 RESTful 设计原则，以资源为中心，使用复数形式，接口命名应做到见名知意
• 路由命名应清晰反映资源和行为，例如：/users/query/{user_id}
• 根据操作使用正确的 HTTP 方法：GET、POST、PUT、PATCH、DELETE
  • GET：获取特定资源或资源列表
  • POST：创建新资源
  • PUT：更新特定资源，如果不存在则创建新资源
  • PATCH：局部更新资源
  • DELETE：删除特定资源

1. HTTP 方法和状态码

• 使用标准 HTTP 状态码，通过 FastAPI 的 status 模块定义响应状态码，确保接口的通用性和标准化
  • HTTP 状态码参考

1. 请求和响应格式

• 接口响应数据内容格式统一使用 JSON类型，指定合适的 MIME 类型
  • MIME类型参考
  • MIME类型参考-国际标准
• 错误响应应提供足够的错误信息以及统一的错误对象格式，通用数据响应模型datamodels.CommonResponse

1. 安全和认证

• 明确接口的认证和授权要求，使用内部已经实现的身份认证RoleChecker类进行操作

@public.get('/test')
def test(userinfo=Depends(RoleChecker('admin'))):  # 方法依赖，可以获取依赖返回的对象
    pass

@public.get('/test', dependencies=[Depends(RoleChecker('admin'))])  # 路由依赖，无法获取依赖返回的对象
def test():
    pass

1. 数据库操作

• 全局 ORM 操作对象：所有数据库操作必须使用全局定义的 ORM 操作对象 database.SessionLocal，以保证数据库操作的一致性和事务管理

• 依赖注入：利用 FastAPI 的依赖注入系统管理数据库会话，例如，使用依赖项来获取和关闭数据库会话

  依赖项示例

# 依赖项示例
def get_db():
    db = database.SessionLocal()
    try:
        yield db
    finally:
        db.close()
        
@public.post("/register/",  summary='用户注册')
def register_user(username: str = Query(default='username', description='用户名'),
                  password: str = Query(default='123456', description='密码'),
                  role: UserRole = Query(default=UserRole.test, description='角色'),
                  db: Session = Depends(get_db)):
                  pass                

1. 接口文档和版本管理

• 自动化文档：利用 FastAPI 自动生成的 Swagger UI 或 Redoc 文档，并确保文档的准确性和实时更新
• 版本管理：在 API 路径中包含版本号，如 /api/v1/...，并在更改功能时更新版本号

1. 错误处理

• 统一异常处理：使用 FastAPI 的异常处理器来捕获并处理预期内外的异常，返回HTTPException统一格式的错误响应

1. 测试

• 编写针对每个接口的单元测试和集成测试，确保接口按预期工作，覆盖主要功能点和边界条件

1. 路由挂载和分组

• 根据功能对路由进行分组和挂载，提高项目的模块化和可维护性

app.include_router(public, prefix='/public', tags=['公共接口'])
app.include_router(test_app, prefix='/test', tags=['测试环境'])
app.include_router(prod_app, prefix='/prod', tags=['生产环境'])

备注

• 注意 uvicorn 版本兼容性问题，以支持热重载（重载会产生意想不到的bug，慎用！！！）
• 维护此项目要遵循以上规范，以保证代码的质量和项目的可维护性
• git提交备注