从零开始配置 starlette web 框架,核心做法是实例化 starlette 对象并注册路由与中间件。你需要定义处理请求的异步函数,通过 @app.route() 装饰器或 app.add_route() 方法将其绑定到具体路径,最后使用 uvicorn 启动应用。这样即可得到一个支持高并发、轻量级的 web 服务。

Starlette 实例如何初始化并挂载路由
初始化 Starlette 实例后,必须显式添加路由才能响应 HTTP 请求。默认情况下,实例不包含任何路由,直接运行会返回 404。开发者需要创建符合 Request 和 Response 接口的处理函数,并将其映射到 URL 模式。这一步决定了应用能接收哪些请求以及如何处理它们。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
import uvicorn
async def homepage(request):
return JSONResponse({"message": "Hello World"})
routes = [
Route("/", homepage),
]
app = Starlette(routes=routes)
if __name__ == "__main__":
uvicorn.run(app, host="127.0.0.1", port=8000)预期结果:访问 http://127.0.0.1:8000/ 将返回 {"message": "Hello World"}。未匹配的路径将触发默认的 404 错误处理逻辑。
如何添加自定义中间件以处理跨域或日志
在路由之外,中间件用于在请求到达处理器之前或之后执行通用逻辑。通过 app.add_middleware() 可以链式添加中间件,例如 CORSMiddleware 用于解决跨域问题,或自定义中间件用于记录请求耗时。中间件的执行顺序遵循后进先出(LIFO)原则,最后添加的中间件最先执行请求预处理,最后执行响应后处理。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.middleware.cors import CORSMiddleware
from starlette.responses import PlainTextResponse
from starlette.routing import Route
import uvicorn
async def data_endpoint(request):
return PlainTextResponse("Data received")
routes = [Route("/data", data_endpoint)]
app = Starlette(routes=routes)
# 添加 CORS 中间件,允许所有来源
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["GET", "POST"],
allow_headers=["*"]
)
if __name__ == "__main__":
uvicorn.run(app, host="127.0.0.1", port=8000)预期结果:来自任意域的 GET 或 POST 请求访问 /data 时,服务器会在响应头中包含 Access-Control-Allow-Origin: *,浏览器不再拦截该请求。
当请求路径包含动态参数时如何处理
当路由定义中包含尖括号包裹的参数(如 <id></id>)时,Starlette 会自动解析路径段并将其作为关键字参数传递给处理函数。开发者需在函数签名中声明同名参数,类型可指定为 str 或 int。若类型不匹配(如期望整数但收到字符串),框架将自动返回 404 而非抛出异常,这有助于保持路由系统的简洁性。
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
import uvicorn
async def get_user(request):
user_id = request.path_params.get("user_id")
return JSONResponse({"user_id": user_id, "status": "found"})
routes = [
Route("/users/{user_id}", get_user),
]
app = Starlette(routes=routes)
if __name__ == "__main__":
uvicorn.run(app, host="127.0.0.1", port=8000)预期结果:访问 /users/123 返回 {"user_id": "123", "status": "found"}。访问 /users/abc 同样返回上述内容,因为默认参数类型为 str。若将路由定义为 Route("/users/{user_id:int}", get_user) 且访问 /users/abc,则返回 404。

















