Litestar CLI 命令行完全参考命令、选项与扩展机制解析【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestarLitestar 内置了一套功能完整的命令行接口CLI用于应用的运行、调试、路由查看、OpenAPI 与 TypeScript 规范生成以及服务端会话管理。本指南以 CLI 参考文档 为核心结合 CLI 使用指南 与litestar/cli下的真实源码实现系统讲解 CLI 的入口结构、全部子命令与选项、应用自动发现规则、环境变量约定以及基于 entry point 和插件的扩展方式帮助读者在真实项目中熟练驾驭litestar命令。CLI 的组成与启用Litestar CLI 由click、rich与rich-click三个库驱动click负责命令行解析rich负责富文本表格与树状输出rich-click则提供带样式与分组的帮助页面。入口代码位于 litestar/cli/init.py其中对 rich-click 做了主题定制THEME star-box、TEXT_MARKUP rich、SHOW_ARGUMENTS True、MAX_WIDTH 120并将帮助表格按 required / opt_long / opt_short / metavar / help 列展示。CLI 默认不会随litestar核心一起安装其依赖被收纳在cliextra 中该 extra 还额外提供uvicornlitestar run的底层 ASGI 服务器与jsbeautifier用于美化litestar schema typescript生成的代码。官方推荐直接安装standardextrapip install litestar[standard]安装完成后即可使用litestar run等命令。如果只装了核心包而缺少click入口会抛出MissingDependencyException(click, extracli)提示安装cliextra见 litestar/main.py。CLI 入口与命令树CLI 的入口是litestar/__main__.py中的run_cli()它从 litestar/cli/main.py 导入根命令组litestar_group并执行。litestar_group是一个click.Group具体类型为LitestarExtensionGroup见 litestar/cli/_utils.py支持-h/--help两种帮助触发方式。其命令树如下litestar ├── --app module:app # 全局显式指定应用 ├── --app-dir path # 全局将目录加入 PYTHONPATH ├── run # 启动 ASGI 服务器依赖 uvicorn ├── info # 显示检测到的应用信息 ├── routes # 显示应用路由 ├── version # 显示版本号 ├── schema │ ├── openapi # 生成 OpenAPI Schema 文件 │ └── typescript # 由 OpenAPI 生成 TypeScript 类型 └── sessions ├── delete session-id # 删除指定会话 └── clear # 清空全部会话命令注册代码集中在 litestar/cli/main.py四个核心命令定义在 litestar/cli/commands/core.pyschema与sessions两个命令组分别位于 litestar/cli/commands/schema.py 与 litestar/cli/commands/sessions.py。全局选项指定应用与工作目录根命令提供两个全局选项--app module_path:app显式指定应用格式为模块名.子模块:应用实例或工厂函数例如litestar --appmy_application.app:create_my_app run。--app-dir 目录将指定目录加入PYTHONPATH用于查找应用模块默认取当前工作目录。LitestarEnv.from_envlitestar/cli/_utils.py负责解析这些配置它会把--app-dir加入sys.path若环境中安装了python-dotenv还会自动加载.env文件随后从--app或环境变量LITESTAR_APP读取应用路径。--app的优先级高于LITESTAR_APP环境变量# 通过 --app 指定应用工厂 litestar --appmy_application.app:create_my_app run # 通过环境变量指定 LITESTAR_APPmy_application.app:create_my_app litestar run应用自动发现规则未显式指定应用时CLI 会执行自动发现_autodiscover_applitestar/cli/_utils.py。发现过程基于常量AUTODISCOVERY_FILE_NAMES [app, application]按以下顺序查找app.pyapp/__init__.pyapp包的子模块递归application.pyapplication/__init__.pyapplication包的子模块递归在这些位置中CLI 按优先级寻找名为app的Litestar实例 → 名为application的Litestar实例 → 任意Litestar实例 → 名为create_app的可调用对象 → 返回类型注解为Litestar的可调用对象。命中后会设置环境变量LITESTAR_APP并打印类似Using app from app:app的提示非 TTY 下自动静默。若一无所获则抛出LitestarCLIException(Could not find Litestar instance or factory)。核心命令详解version查看版本litestar version # 输出完整版本如 2.12.0final0 litestar version -s # 或 --short仅输出 x.y.z-s/--short会剔除 release levelalpha/beta/rc/final与 serial 信息。版本解析与格式化逻辑位于 litestar/utils/version.py其中Version.formatted()负责拼接字符串。info查看应用信息litestar info该命令调用show_app_infolitestar/cli/_utils.py以 rich 表格输出当前应用的诊断信息包括Litestar 版本、Debug 模式开关、异常时是否进入 PDB、CORS/CSRF 是否启用、Allowed hosts、OpenAPI 路径、压缩后端如 brotli、模板引擎类型以及已注册的中间件列表。下图是典型输出run启动服务器run是使用频率最高的命令底层委托uvicorn运行。若未安装 uvicorn命令会打印提示并退出exit code 1提示安装litestar[standard]。全部选项如下选项别名默认值环境变量说明--reload-rFalseLITESTAR_RELOAD文件变更时自动重载--reload-dir-R无LITESTAR_RELOAD_DIRS监听变更的目录逗号分隔可多次指定--reload-include-I无LITESTAR_RELOAD_INCLUDES参与监听的 glob 模式--reload-exclude-E无LITESTAR_RELOAD_EXCLUDES排除的 glob 模式--port-p8000LITESTAR_PORT监听端口--web-concurrency-W/--wc1LITESTAR_WEB_CONCURRENCY/WEB_CONCURRENCYworker 数上限为 CPU 核数 1--host-H127.0.0.1LITESTAR_HOST监听地址--fd-F无LITESTAR_FILE_DESCRIPTOR绑定到指定文件描述符对应的 socket--uds-U无LITESTAR_UNIX_DOMAIN_SOCKET绑定 UNIX domain socket--debug-dFalseLITESTAR_DEBUG以调试模式运行--use-pdb-P/--pdbFalseLITESTAR_PDB异常时进入 PDB--ssl-certfile无无LITESTAR_SSL_CERT_PATHSSL 证书文件路径--ssl-keyfile无无LITESTAR_SSL_KEY_PATHSSL 私钥文件路径--create-self-signed-cert无FalseLITESTAR_CREATE_SELF_SIGNED_CERT证书/私钥不存在时自动生成自签名证书--quiet-console-qFalseLITESTAR_QUIET_CONSOLE抑制格式化输出适用于 CI/CD 与非 TTY 环境几点实现细节值得注意重载与多 worker 走子进程当workers 1且未开启重载时直接在当前进程调用uvicorn.run(...)否则通过子进程执行python -m uvicorn ..._run_uvicorn_in_subprocesslitestar/cli/commands/core.py。源码注释指出子进程方案是为了规避 uvicorn 的--reload与--workers配合时的已知问题。--debug/--pdb通过环境变量传递命令会设置LITESTAR_DEBUG1/LITESTAR_PDB1供应用初始化时读取。自签名证书--create-self-signed-cert依赖cryptography库需安装litestar[cryptography]extra生成有效期 365 天、CN 为localhost的 RSA-2048 证书与无密码私钥_generate_self_signed_certlitestar/cli/_utils.py。server lifespan服务器启动前会先进入_server_lifespan上下文litestar/cli/commands/core.py确保server_lifespan钩子在整个服务器生命周期而非单个 worker内只执行一次。routes查看路由litestar routes # 默认隐藏 schema 路由 litestar routes --schema # 包含 OpenAPI schema 路由 litestar routes --exclude ^/admin # 用正则排除匹配的路由可多次指定路由按路径排序后以 richTree形式渲染_RouteTreelitestar/cli/commands/core.pyHTTP 路由展示处理器名、async/sync标记与 HTTP 方法集合ASGI 与 WebSocket 路由则标注(ASGI)/(WS)类型。默认会过滤掉 OpenAPI 默认 schema 路由--schema可将其纳入展示--exclude接受正则非法正则会被跳过并给出提示。效果见下图schema 命令组生成 OpenAPI 与 TypeScript 规范schema组用于把应用暴露的 OpenAPI 规范导出为文件# 生成 OpenAPI Schema默认输出 openapi_schema.json litestar schema openapi litestar schema openapi --output openapi.yaml # 支持 .json/.yml/.yaml # 生成 TypeScript 类型定义默认输出 api-specs.ts litestar schema typescript litestar schema typescript --output client.ts --namespace MyAPIschema openapi --output默认openapi_schema.jsonJSON 输出会经过msgspec.json.format缩进美化YAML 输出使用pyyaml懒加载未安装时抛出MissingDependencyException(pyyaml, extrayaml)见 litestar/cli/commands/schema.py。schema typescript --output默认api-specs.ts与--namespace默认API由litestar._openapi.typescript_converter将 OpenAPI schema 转换为 TypeScript 类型若安装了jsbeautifier会先美化再写盘litestar/cli/commands/schema.py。sessions 命令组管理服务端会话当应用启用了SessionMiddleware且后端为服务端后端ServerSideSessionBackend时可用以下命令管理会话litestar sessions delete session-id # 删除单个会话带确认提示 litestar sessions clear # 删除全部会话带确认提示get_session_backendlitestar/cli/commands/sessions.py遍历应用的中间件列表定位SessionMiddleware实例并取出backend未安装会话中间件或后端非服务端时抛出LitestarCLIException。删除操作通过anyio.run异步执行backend.delete而clear要求存储后端实现delete_all例如内存与 Redis 后端否则报错。两个命令都会用rich.prompt.Confirm弹出交互式确认适合在 CI 场景外谨慎使用。环境变量速查除选项对应的环境变量外还有两个与命令行无关的环境变量环境变量说明LITESTAR_APP指定应用路径--app优先于它LITESTAR_APP_NAME自定义日志中应用的名字默认LitestarLITESTAR_PORT/LITESTAR_HOST端口与主机run的默认值来源LITESTAR_RELOAD/_DIRS/_INCLUDES/_EXCLUDES重载开关与监听范围LITESTAR_WEB_CONCURRENCY、WEB_CONCURRENCYworker 数后者为 Heroku 等平台通用变量LITESTAR_DEBUG/LITESTAR_PDB调试模式与 PDB 开关LITESTAR_SSL_CERT_PATH/LITESTAR_SSL_KEY_PATHSSL 证书与私钥路径LITESTAR_CREATE_SELF_SIGNED_CERT自动生成自签名证书LITESTAR_QUIET_CONSOLE抑制富文本输出日志/CI 场景LITESTAR_FILE_DESCRIPTOR/LITESTAR_UNIX_DOMAIN_SOCKETsocket 绑定方式扩展 CLIentry point 与插件CLI 的扩展点有两个详见 CLI 使用指南1. 通过 entry point 注册命令在litestar.commands分组下注册一个click.Command或click.Group。根组LitestarExtensionGroup会通过importlib.metadata.entry_points自动加载它们litestar/cli/_utils.py。以pyproject.toml为例[project.entry-points.litestar.commands] my_command my_litestar_plugin.cli:main2. 通过CLIPlugin插件钩子继承CLIPlugin并实现on_cli_init(self, cli: Group)在 CLI 初始化时向根组添加或覆盖命令from litestar import Litestar from litestar.plugins import CLIPlugin from click import Group class MyPlugin(CLIPlugin): def on_cli_init(self, cli: Group) - None: cli.command() def is_debug_mode(app: Litestar): print(app.debug) app Litestar(plugins[MyPlugin()])3. 在命令中注入app实例无论用哪种方式扩展只需在命令函数签名中加入app: Litestar参数_inject_argslitestar/cli/_utils.py就会在调用前自动注入已加载的应用实例同样可注入env: LitestarEnv与ctx: click.Context。此外插件还可以实现server_lifespan钩子让初始化代码如建数据库表在整个服务器生命周期只运行一次即使run启动了多个 workerfrom contextlib import contextmanager from typing import Generator from litestar import Litestar from litestar.plugins.base import CLIPlugin class StartupPrintPlugin(CLIPlugin): contextmanager def server_lifespan(self, app: Litestar) - Generator[None, None, None]: print(i_run_before_startup_plugin) try: yield finally: print(i_run_after_shutdown_plugin) def create_app() - Litestar: return Litestar(route_handlers[], plugins[StartupPrintPlugin()])易用性细节错误选项智能提示LitestarGroup.parse_args捕获NoSuchOption并交给suggest_optionlitestar/cli/_suggestions.py处理例如输入-V或--version时会建议改用version子命令而不是直接报错。帮助信息随时运行litestar --help查看最权威的命令帮助自动化生成的 Click API 参考即 CLI 参考文档 本身。测试覆盖CLI 行为有完整的单元测试支撑包括 test_core_commands.pyrun/routes/info/version、test_schema_commands.pyopenapi/typescript、test_session_commands.py会话管理、test_env_resolution.py环境变量解析与 test_ssl.pySSL 文件校验与自签名证书可作为自定义扩展时的参照。综合来看Litestar CLI 以「click 解析 rich 渲染 uvicorn 承载」为骨架把应用发现、运行调试、路由诊断、规范导出与会话运维统一到一条命令之下同时通过 entry point 与CLIPlugin提供了清晰的二次开发边界。无论是日常开发、CI/CD 部署还是团队工具链集成都可以从这套 CLI 中直接受益。【免费下载链接】litestarLight, flexible and extensible ASGI framework | Built to scale项目地址: https://gitcode.com/GitHub_Trending/li/litestar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考