FastAPI 官方文档解读 (一)

Posted 2023-04-19

参考技术A

标准安装

完整安装

uvicorn 模块名:app --port=8000 --host=127.0.0.1

API的标准，由 Swagger UI 提出。API文档的基础便是 OpenAPI

例如 http://127.0.0.1:8000/items/foo 这种形式，在 @app.get("/items/item_id") 环境下， foo 为 item_id 的值，在下方可以 def read_item(item_id: int): 这样接收。

新建一个枚举类应用于参数类型

API文档 会很聪明的知道，参数必须限制在 枚举类 中的一个。但API还不清楚这个参数的类型。

只需要让 枚举类 继承例如 str 即可，请您放心， FastAPI 足够聪明。

例如 /files/home/johndoe/myfile.txt ，您的期望是 /files/file_path 。也就是将 home/johndoe/myfile.txt 解析为 file_path 。
您需要改写为 /files/file_path:path ，这样便可捕获到。

常见的 www.example.com/?name=abc&age=5 形式

如果需要接收 bool 值，不必遵循什么规则。 yes ， on ， True ， true ， 1 ......皆可被转化。请您放心， FastAPI 足够聪明。

就像正常Python那样标注

具有默认值的参数，则是 非必需 的。
当然有时候 = 后面未必代表的是默认值(这个以后谈起)

正常像 typing 那样使用即可

Model 可用于 body 中的JSON序列，可以是request的 body ，也可以是response的 body

在 request 和 response 中分别使用 Model

查询参数可使用 Query() 进行验证，可设置许多属性，包括大于，小于，长度，默认值等。
q: str = Query(None) & q: str = None 这两种情况是等价的。
当然如果你把第一个参数（default=）设置为 ... 是，这就变成了 必填参数 ，即便你已经 q = Query() 这种形式，但 Query 这样就不能其默认值作用

有趣的是，当你更改一下类型声明例如
def read_items(q: Optional[List[str]] = Query(None)): ， List[str] 会使得 q 可以存在多个
http://localhost:8000/items/?q=foo&q=bar 例如这样的形式便是被允许的。此时这个q会由 str 变为 list
def read_items(q: List[str] = Query(["foo", "bar"])): 像这样你也可以为其添加默认值
def read_items(q: list = Query([])) 再例如这样的情况，注意，这个并未限制元素的类型。

例如 deprecated=True 可以将参数弃用，再例如 alias 可以给参数起个别名。

使用 Path() 便可以达到同样效果，注意，路径参数永远都是必须的。所以您最少也要应该写上 ... 作为default

q: str 和 p: str = Path(...) ，这些写法都是可以的。但是如果您是强迫症，想定义他们的顺序。可能会碰到一些问题。python不允许带有默认值的参数，在不带有默认值的参数的前面。这会导致您不能像下面这种书写方式

这是python语法上不允许的
为了解决这个问题，您可以在最前面加一个 * 作为参数

python不会对这个 * 做什么，但是会将其后面所有的参数都解析成 kwargs 形式。即便其没有写默认值。

请注意，这里 * 前面的参数照旧，但 * 后面的参数不允许用位置参数，而必须指定参数名。

这里主要是讲JSON格式的Body，当我们需要一个model时，我们期待的body格式如下

但是如果我们需要两个model，例如：

这种情况下，如果我们像如下这样是不可以的。因为这不符合JSON的格式。

正确写法

一定要注意 单model 和 多model 的区别

这种情况下，这个id会被解析为查询参数。但如果您想让它也成为body体中的一部分。

例如这是您所期待的，您希望id: int所解析的是body中的这个。那么您可以使用 Body()

这时，上面形式的JSON就会如您所愿解析了。

我们知道，该参数的期望body是

但如果我们希望的格式是如下的，该怎么做？

我们知道，只有两个以上model时，才会自动变成key，value形式。
实际上我们只需要稍作加工

便可以完成我们所期望的

Spring 总览及 IOC 容器的使用 —— Spring 官方文档解读

Spring 总览及 IOC 容器的使用 —— Spring 官方文档解读（一）

什么是 Spring？

spring 这个词在不同情况下有不同意义。可以指 Spring 框架本身，但更多地被用来表示 Spring 整个家族的产品。

设计理念

学习框架必须要知道它的设计理念，Spring 框架有着以下的理念：

• Spring 让你在架构种的各个层面有更多的选择，并且允许你尽晚的做出决策。比如，你在项目完成后可以通过更改配置来切换持久层的提供者。
• Spring 具有强大的灵活性，它不在意你是如何完成工作的，它尽可能多地支持不同的应用需求。
• Spring 具有强大的向后兼容性。Spring 的更新都是精心设计的，而且它对 JDK 的版本要求也是经过精心挑选的，这让你很容易就能更新你的产品。
• Spring 团队对 API 的设计十分谨慎，这使得这些 API 在很多版本种都是完全通用的，而且可以使用好几年。
• Spring 本身的代码非常简洁，而且具有非常易于阅读的 javadoc，它是极少数只写有意义的代码的项目，而且它的包之间，没有循环依赖。

控制反转容器（IOC Container）

IOC 介绍

IOC 也被称为依赖注入（dependency injection (DI)），程序员通过设定构造参数、工厂方法的参数等手段来确立各个对象之间的关系，这样，当程序员创建 bean 的时候，相应的依赖会被容器自动的注入到 bean 中，不需要程序员在创建 bean 的时候手动新建那些对象。这使得依赖更容易被管理。（被称为控制反转是因为不再是程序员去将依赖手动注入到相应 bean 中，而是通过容器自动地注入）

org.springframework.beans 和 org.springframework.context 这两个包是 Spring IOC 容器地基础。接口 BeanFactory 提供了一种能够管理任何类型对象的高级配置机制。ApplicationContext 是 BeanFactory 的一个子接口，它多出了这些功能：

• 更容易与 Spring 的 AOP 进行集成
• 消息资源处理（用于国际化）
• 事件发布
• 特定的 Context（例如 web 应用中的 WebApplicationContext）

总而言之，BeanFactory 提供了基础的功能，而 ApplicationContext 提供了特定的高级功能，是 BeanFacotry 的超集。（通常只有在与其他框架整合的时候才会使用 BeanFactory）

容器总览

org.springframework.context.ApplicationContext 接口代表了 Spring IOC 容器，它负责通过读取配置元素据来对 bean 进行实例化、组装、配置。元数据的编写方式有三种：XML，Java 注解或者 Java 代码。你可以通过它来构建复杂的对象间依赖关系。

Spring 提供了不少 ApplicationContext 的实现，在独立应用中，最常见的有 ClassPathXmlApplicationContext 和 FileSystemXmlApplicationContext。XML 是最常用的编写元数据的格式。你也可以通过编写少量的 XML 配置使得它可以支持读取来自注解或者代码的元数据。

在大部分场景下，用户不用显示地实例化一个或多个 IOC 容器。

编写元数据配置并使用

通过上述的内容，我们可以知道 Spring IOC 容器是通过元数据来了解各个对象之间的关系的。最传统的编写元数据的方法为使用 XML 配置文件。（当然这不是唯一的方式，现在更多的人会使用注解或者代码来编写元数据）。当然，你也可以配合 AOP 来配置 IOC 管理之外的对象。（这部分将在后续内容出现。）

现在，我们来看下基于 XML 的元数据的基本编写方式：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        https://www.springframework.org/schema/beans/spring-beans.xsd">

    <bean id="..." class="...">
        <!-- id 属性用于指定该 bean 的名字，而 class 属性需要写入一个完整的 classname 来确定为那个类的对象，比如 top.dragondove.demo.bean.Hero -->
        <!-- collaborators and configuration for this bean go here -->
    </bean>

    <bean id="..." class="...">
        <!-- collaborators and configuration for this bean go here -->
    </bean>

    <!-- more bean definitions go here -->

</beans>

编写完之后，我们该实例化这个容器并且获取容器中的内容了，下面是一个例子。

ApplicationContext context = new ClassPathXmlApplicationContext("services.xml", "daos.xml");
Hero dove = context.getBean("dove", Hero.class);
System.out.println(dove);

以上是 Spring 容器的简单使用，下一章节将会讲解更多的元数据配置内容及配置方式。本次内容的完整代码在下面列出，至于 Spring 项目的初始化可以直接使用 Spring Boot （采用官网的 spring boot initializr 即可，依赖全都不选即可）：

// src/main/java/top/dragondove/demo/bean/Hero.java
package top.dragondove.demo.bean;

// 普通的 javabean
public class Hero 

    private String name;
    private Integer age;

    public String getName() 
        return name;
    

    public Integer getAge() 
        return age;
    

    public void setName(String name) 
        this.name = name;
    

    public void setAge(Integer age) 
        this.age = age;
    

    @Override
    public String toString() 
        return "Name: " + name + ", Age: " + age;
    

<!-- src/main/resources/applicationContext.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        https://www.springframework.org/schema/beans/spring-beans.xsd">
    <!-- 配置 bean 的元数据 -->
    <bean id="dove" class="top.dragondove.demo.bean.Hero">
        <property name="name" value="Dove" />
        <property name="age" value="18" />
    </bean>
</beans>

// src/main/java/top/dragondove/demo/DemoApplication.java
package top.dragondove.demo;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import top.dragondove.demo.bean.Hero;

public class DemoApplication 

    private static ApplicationContext context;

    public static void main(String[] args) 
        context = new ClassPathXmlApplicationContext("applicationContext.xml");
        Hero dove = context.getBean("dove", Hero.class); // 获取容器中 id 为 dove 的对象并确定其类型为 Hero 类型。
        System.out.println(dove);
    

运行 DemoApplication 里的 main 方法即可看到效果。