Typer 默认按字母顺序排列 CLI 命令，但可通过自定义 TyperGroup 子类重写 list_commands 方法，强制保留代码中 @app.command() 的声明顺序。
typer 默认按字母顺序排列 cli 命令，但可通过自定义 `typergroup` 子类重写 `list_commands` 方法，强制保留代码中 `@app.command()` 的声明顺序。
在使用 Typer 构建命令行工具时，一个常见且易被忽视的问题是：命令在 --help 输出中的显示顺序并非代码定义顺序，而是按命令名的字典序自动排序。例如，即使你先定义 change_value、再定义 close_field、最后定义 add_transaction，帮助信息中仍可能显示为 add_transaction → change_value → close_field。这对用户友好性和命令逻辑分组会造成干扰。
要解决此问题，需绕过 Typer（底层基于 Click）对命令列表的默认排序行为。核心思路是：提供一个自定义的 CommandGroup 类，覆盖其 list_commands() 方法，直接返回 self.commands 的原始插入顺序（Python 3.7+ 中 dict 保持插入序）。
以下是完整、可直接运行的解决方案：
import typer
from click import Context
from typer.core import TyperGroup
class OrderCommands(TyperGroup):
def list_commands(self, ctx: Context) -> list:
# 直接返回 commands 字典的键列表，保持定义顺序
return list(self.commands)
app = typer.Typer(
cls=OrderCommands, # 注入自定义分组类
no_args_is_help=True # 无参数时自动显示帮助
)
@app.command()
def change_value(file_name: str, field: str):
"""修改指定文件中字段的值"""
print(f"Here I will change the {file_name} {field}")
@app.command()
def close_field(file_name: str, field: str):
"""关闭指定文件中的字段"""
print(f"I will close field {field} in {file_name}")
@app.command()
def add_transaction(file_name: str):
"""向指定文件添加一笔交易记录"""
print(f"I will add the transaction to {file_name}")
if __name__ == "__main__":
app()
✅ 关键说明：
- TyperGroup 是 Typer 内部用于管理子命令的 Click Group 子类，其 self.commands 是一个 dict，在 Python ≥3.7 中天然保持插入顺序；
- list_commands() 被 Click 在生成帮助文本时调用，原实现返回 sorted(self.commands.keys())，我们将其替换为 list(self.commands) 即可打破字母序；
- 必须通过 cls=OrderCommands 显式传入 Typer 构造器，否则无效；
- 此方案兼容 Typer 所有特性（如参数类型注解、嵌套子命令、回调等），无需修改命令定义方式。
⚠️ 注意事项：
- 不要尝试通过 app.registered_commands 或手动修改 app._registered_commands —— 这些是内部属性，不稳定且易失效；
- 避免继承 typer.Typer 并重写 add_command：它不控制 help 渲染顺序；
- 若使用 @app.callback() 或子应用（typer.Typer() 实例作为子命令），请确保子应用也使用相同 cls 配置，否则子命令仍会按字母排序。
通过这一轻量级定制，你的 CLI 帮助界面将严格遵循开发者的意图呈现命令流，显著提升可维护性与终端用户体验。
