APIStar 框架入门：Python 3 异步与类型提示驱动的 API 开发

在Python中快速构建API时，我通常首选Flask。最近，我发现了一个名为APIStar的基于Python 3的新兴API框架，并对此产生了浓厚兴趣。该框架充分利用了Python的新特性，包括类型提示（Type Hints）和asyncio异步支持，同时为开发者提供了极佳的开发体验。在深入探讨这些功能之前，我要特别感谢Tom Christie，他不仅开发了Django REST Framework，还创造了APIStar框架。

回到APIStar本身，这是一个高效且功能丰富的框架。开发者可以选择基于asyncio编写异步代码，也可以沿用传统的WSGI后端模式。框架内置了名为apistar的命令行工具，能显著提升开发效率。它可选地支持Django ORM和SQLAlchemy数据库操作。其强大的类型系统允许定义输入输出的约束条件，APIStar能据此自动生成API模式（包括文档），并提供数据验证和序列化功能。尽管APIStar专注于API构建，但也能轻松用于搭建Web应用程序。在动手实践之前，这些特性可能显得抽象，接下来我们将通过实例进行说明。

开始

首先从安装APIStar开始。建议为本次实验创建一个虚拟环境。如果尚不清楚如何创建虚拟环境，请继续阅读后续步骤。

pip install apistar

（上述命令适用于Python 3虚拟环境）

若未使用虚拟环境，或Python 3的pip命令名为pip3，请使用 pip3 install apistar 代替。

安装完成后，即可使用apistar命令行工具。我们可以利用它创建新项目，例如在当前目录下初始化一个新项目。

apistar new .

接下来需要创建两个文件：app.py，用于存放主应用程序代码；以及test.py，用于执行测试。让我们先查看app.py文件的内容。

from apistar import Include, Route
from apistar.frameworks.wsgi import WSGIApp as App
from apistar.handlers import docs_urls, static_urls
def welcome(name=None):
if name is None:
return {'message': 'Welcome to API Star!'}
return {'message': 'Welcome to API Star, %s!' % name}
routes = [
Route('/', 'GET', welcome),
Include('/docs', docs_urls),
Include('/static', static_urls)
]
app = App(routes=routes)
if __name__ == '__main__':
app.main()

在深入分析代码之前，我们先运行应用程序以验证其是否正常工作。在浏览器中访问 http://127.0.0.1:8080/，将收到如下响应。

{"message": "Welcome to API Star!"}

若访问地址：http://127.0.0.1:8080/?name=masnun

{"message": "Welcome to API Star, masnun!"}

同样地，访问 http://127.0.0.1:8080/docs/，我们将看到自动生成的API文档页面。

该文档界面展示了在app.py中定义的函数，并允许用户交互式地查看函数返回值。

例如，若定义一个名为show_task的函数，其输入参数为task_id，返回值为该任务的详细信息，那么在交互界面中输入一个有效的task_id即可查询并返回结果。

现在我们来解析代码。其中有一个welcome函数，接收一个名为name的参数，默认值为None。APIStar是一个智能的API框架，它会自动尝试从URL路径或查询字符串中查找名为name的键，并将其传递给函数，同时基于此生成API文档。这确实非常便捷。

随后，我们创建了一个包含Route和Include实例的列表，并将该列表传递给App实例。Route对象用于定义用户自定义路由；而Include则用于包含指定路径下的其他URL路径集合。

路由

路由配置十分简单。在构造App实例时，需传递一个routes参数，该参数应为由Route或Include对象组成的列表。对于Route，需指定URL路径、HTTP方法以及可调用的请求处理程序（函数或其他可调用对象）。对于Include实例，则需指定URL路径和包含的Routes实例列表。

路径参数

可以在花括号内添加名称来声明URL路径参数。例如 /user/{user_id} 定义了一个URL，其中user_id是路径参数，即一个将被注入到处理函数（实际上是可调用对象）中的变量。以下是一个简单的示例。

from apistar import Route
from apistar.frameworks.wsgi import WSGIApp as App
def user_profile(user_id: int):
return {'message': 'Your profile id is: {}'.format(user_id)}
routes = [
Route('/user/{user_id}', 'GET', user_profile),
]
app = App(routes=routes)
if __name__ == '__main__':
app.main()

若访问 http://127.0.0.1:8080/user/23，将得到如下响应。

{"message": "Your profile id is: 23"}

但如果尝试访问 http://127.0.0.1:8080/user/some_string，则无法匹配。这是因为我们定义了user_profile函数，并为user_id参数添加了类型提示（int）。如果传入的不是整数，路径将不匹配。然而，若删除类型提示，仅使用user_profile(user_id)，则任何字符串都能匹配此URL。这也展示了APIStar利用类型提示进行智能匹配的优势。

包含/分组路由

有时将某些URL组合在一起是有意义的。假设我们有一个处理用户相关功能的user模块，将所有与用户相关的URL分组在/user路径下可能更为合适。例如 /user/new、/user/1、/user/1/update 等。我们可以轻松地在单独的模块或包中创建处理程序和路由，然后将它们包含在主路由中。

让我们创建一个名为user的新模块，文件名为user.py。将以下代码放入该文件。

from apistar import Route
def user_new():
return {"message": "Create a new user"}
def user_update(user_id: int):
return {"message": "Update user #{}".format(user_id)}
def user_profile(user_id: int):
return {"message": "User Profile for: {}".format(user_id)}
user_routes = [
Route("/new", "GET", user_new),
Route("/{user_id}/update", "GET", user_update),
Route("/{user_id}/profile", "GET", user_profile),
]

现在可以从app主文件中导入user_routes，并按以下方式调用。

from apistar import Include
from apistar.frameworks.wsgi import WSGIApp as App
from user import user_routes
routes = [
Include("/user", user_routes)
]
app = App(routes=routes)
if __name__ == '__main__':
app.main()

此时，/user/new 将委托给user_new函数处理。

访问查询字符串/查询参数

查询字符串中传递的任何参数都可以直接注入到处理函数中。例如URL /call?phone=1234，处理函数可以定义一个phone参数，它将从查询字符串/查询参数中接收值。如果URL查询字符串不包含phone的值，则将获得None。我们还可以为参数设置默认值，如下所示。

def welcome(name=None):
if name is None:
return {'message': 'Welcome to API Star!'}
return {'message': 'Welcome to API Star, %s!' % name}

在上面的示例中，我们为name设置了默认值None。

注入对象

通过给请求处理程序添加类型提示，我们可以将不同的对象注入到视图中。注入与请求相关的对象有助于处理程序直接从内部访问它们。APIStar内置的http包中提供了几个内置对象。我们也可以利用其类型系统创建自定义对象并将其注入到函数中。APIStar还根据指定的约束进行数据验证。

让我们定义自己的User类型，并将其注入到请求处理程序中。

from apistar import Include, Route
from apistar.frameworks.wsgi import WSGIApp as App
from apistar import typesystem
class User(typesystem.Object):
properties = {
'name': typesystem.string(max_length=100),
'email': typesystem.string(max_length=100),
'age': typesystem.integer(maximum=100, minimum=18)
}
required = ["name", "age", "email"]
def new_user(user: User):
return user
routes = [
Route('/', 'POST', new_user),
]
app = App(routes=routes)
if __name__ == '__main__':
app.main()

现在，如果我们发送如下请求。

curl -X POST
http://127.0.0.1:8080/
-H 'Cache-Control: no-cache'
-H 'Content-Type: application/json'
-d '{"name": "masnun", "email": "masnun@gmail.com", "age": 12}'

猜猜会发生什么？我们将收到一个错误，提示年龄必须等于或大于18。类型系统允许我们进行智能数据验证。如果启用了docs URL，这些参数也将被自动记录。

发送响应

如果你已经注意到，到目前为止，我们只能传递一个字典，它将被转换为JSON并作为默认返回。但是，我们可以使用apistar中的Response类来设置状态码和其他任意响应头。以下是一个简单的示例。

from apistar import Route, Response
from apistar.frameworks.wsgi import WSGIApp as App
def hello():
return Response(
content="Hello".encode("utf-8"),
status=200,
headers={"X-API-Framework": "API Star"},
content_type="text/plain"
)
routes = [
Route('/', 'GET', hello),
]
app = App(routes=routes)
if __name__ == '__main__':
app.main()

它应该返回纯文本响应和一个自定义标头响应头。请注意，content应该是字节，而不是字符串。这就是我在代码中进行编码的原因。

继续

我刚刚介绍了APIStar的一些特性。APIStar中还有许多非常酷的功能，建议通过Github Readme（https://github.com/encode/apistar）文件来了解这个优秀框架所提供的不同功能的更多信息。

总结

以上就是这篇文章的全部内容，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，谢谢大家对本站的支持。如果你想了解更多相关内容请查看下面相关链接