基于FastAPI的接口开发规范

规范既是为了接口可读性，也是方便同事间的协作。

说明：这个规范更多是针对算法工程师，对于后端开发工程师，接口开发规范还需要依次做进一步的细化。

0x01 接口设计基础原则

在说明接口开发规范之前，先说几个基础的原则：

• 接口统一使用UTF8编码；
• 接口的输入输出统一使用JSON的格式，除非特别说明；
• 接口统一使用POST传输数据，为了简单起见，我们不区分post，put之类的区别；
• 图像统一使用Base64编码进行传输；
• 函数名统一使用下划线连接，类名则统一使用驼峰命名；
• 接口和实现分离，接口只干接口的事情，就是定义输入输出，还有参数类型转换等，具体功能调用实现的函数进行实现：

response_model: 这个是定义输出

params：这个是定义输入

上面图示，还对图像参数进行了转换，因为接口传图像使用的都是base64，使用的时候，都使用转换成相应的格式。

• 接口应该要有基础说明，包括标题，版本号，描述信息等，如下:

对应的配置代码：

描述信息description是支持markdown格式的。

0x02 命名及字段规范

• 接口命名规范，样例：

接口的名字是接口的门面，可读性的因素，名字格式：

/object/action

其中object是操作对象，是一个名词，如上面的watermark, seal, object等，而action是动作，是一个动词，如remove，compare等。object和action应该都是一个英文单词，不应该出现下划线，更加不应该出现所谓驼峰命名，代码如：

@app.post('/watermark/remove', response_model=RMWatermarkResp,
          summary="水印去除")

其中summary是定义接口的说明，就是显示在上图中的文字。

• 接口入口文件main.py，输入输出参数配置文件main_settings.py。
• Item是类名，采用驼峰命名，最后以Item结尾，可以继承，如：

Item可以直接用于响应客户端，也可以包装成响应的类，如：

class LineDetectResp(BaseModel):
    lines: List[LineItem] = Field([], title='文本行', example=[])
    tables: List[TableItem] = Field([], title='表格', example=[],
                                    description='当open_table=true时，该字段才存在')
    paragraphs: List[ParagraphItem] = Field([], title='段落', example=[],
                                            description='')

如果是单一对象，则可以命名为Item类，如果不太单一的，则可以命名为Resp类（类名以Resp结尾）。

• 输入参数类名统一命名为Params类，类名以Params结尾，类可以继承：

• Field字段信息，主要包含几个方面：
  • 默认值：若定义为...，则表示该参数是必须的；
  • 字段类型：除了基础类型，也可以使用List定义列表；
  • title：字段说明标题；
  • description：字段说明；
  • example：字段样例值；
  • ge, gt, le, lt: 如果是int或者float类型，可以使用这个参数定义值的范围；
  • min_length, max_length: 如果是str类型，则可以定义字符串长度的范围；
  • min_items, max_items: 如果是列表类型，则可以定义列表元素的数量。

字段还有其他的信息可以设置，具体可以参照Field的文档说明。这些字段信息，主要有两方面作用，一方面是用于展示，另一方面用于参数校验，参数校验能省下不少代码。

对于规范，很多时候是需要秉持一种“强迫症”，一个变量命名，一个空格，一个逗号，也是不应该大意的。