OpenCode 实践课：4 分钟用 Python 写出一个命令行 JWT 解析工具

项目介绍

JWT（JSON Web Token）是前后端分离架构中最常用的身份认证方式。开发调试时经常需要快速查看一个 JWT 里到底装了哪些数据——去 jwt.io 粘贴又麻烦，手写 base64 解码又容易出错。

今天用 OpenCode 写一个命令行 JWT 解析工具，输入一个 JWT 字符串，直接输出格式化后的 Header、Payload 和签名信息。纯 Python 标准库实现，约 100 行代码。

最终效果：

$ python jwt_decoder.py eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

═══════════════════════════════════
  HEADER
═══════════════════════════════════
{
  "alg": "HS256",
  "typ": "JWT"
}

═══════════════════════════════════
  PAYLOAD
═══════════════════════════════════
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

准备工作

• Python 3.8+（本文使用 Python 3.11）
• 已安装 OpenCode（终端输入 opencode 即可启动）

实践过程

第一步：创建项目文件

我对 OpenCode 说：

> 帮我创建一个 Python 命令行 JWT 解析工具。文件名为 jwt_decoder.py，接收一个命令行参数作为 JWT 字符串，解析出 header 和 payload 并以格式化 JSON 输出。

OpenCode 响应并创建了基础代码框架，包含 argparse 参数解析和 base64 解码逻辑。它自动处理了 JWT 的 Base64Url 解码——把 - 替换为 +、_ 替换为 /，并补齐缺失的 = 填充符。这是一个容易踩坑的细节，但 OpenCode 直接帮我们处理好了。

第二步：添加签名信息展示和颜色输出

基础功能跑通后，我对 OpenCode 说：

> 在输出中增加第三部分，显示 Signature（签名），用十六进制格式展示前 8 个字节。另外，给 section 标题加上 ANSI 颜色，header 用蓝色，payload 用绿色，signature 用黄色。

OpenCode 立即在代码中加入了 ANSI 转义序列常量，并为三个部分分别设置了不同颜色。Signature 部分使用 bytes.hex() 输出十六进制字符串。

第三步：增加输入验证和错误提示

为了让工具更健壮，我对 OpenCode 说：

> 增加输入校验：检查 JWT 格式是否包含两个点号分隔符；检查 base64 解码是否成功；如果 token 来自命令行参数可能被 shell 截断，给出友好提示。

OpenCode 添加了多项校验：检查点号数量、捕获 binascii.Error 异常、并针对常见问题（如参数包含空格导致被 shell 分割）给出了中文提示信息。

整个过程中，我只需要用自然语言描述需求，OpenCode 自动完成了：

• 代码编写（标准库零依赖）
• 边界情况处理（Base64Url padding、特殊字符转义）
• 格式化输出（彩色终端文本）

完整代码

import sys
import json
import base64
import argparse

BLUE = "\033[94m"
GREEN = "\033[92m"
YELLOW = "\033[93m"
RESET = "\033[0m"
BOLD = "\033[1m"


def b64url_decode(data: str) -> bytes:
    data = data.replace("-", "+").replace("_", "/")
    padding = 4 - len(data) % 4
    if padding != 4:
        data += "=" * padding
    return base64.b64decode(data)


def print_section(title: str, content: str, color: str):
    line = "═" * 36
    print(f"\n{color}{BOLD}{line}")
    print(f"  {title}")
    print(f"{line}{RESET}")
    print(content)


def main():
    parser = argparse.ArgumentParser(description="JWT 解析工具")
    parser.add_argument("token", help="JWT 字符串")
    args = parser.parse_args()

    token = args.token.strip()

    parts = token.split(".")
    if len(parts) != 3:
        print("错误：JWT 格式不正确，应包含两个点号分隔的三个部分。", file=sys.stderr)
        print("提示：如果 shell 截断了参数，请给 token 加上引号。", file=sys.stderr)
        sys.exit(1)

    header_b64, payload_b64, signature = parts

    try:
        header_bytes = b64url_decode(header_b64)
        payload_bytes = b64url_decode(payload_b64)
    except Exception:
        print("错误：Base64 解码失败，请检查 token 是否完整。", file=sys.stderr)
        sys.exit(1)

    try:
        header = json.loads(header_bytes)
        payload = json.loads(payload_bytes)
    except json.JSONDecodeError:
        print("错误：header 或 payload 不是有效的 JSON。", file=sys.stderr)
        sys.exit(1)

    print_section("HEADER", json.dumps(header, indent=2, ensure_ascii=False), BLUE)

    print_section("PAYLOAD", json.dumps(payload, indent=2, ensure_ascii=False), GREEN)

    try:
        sig_bytes = b64url_decode(signature)
        sig_hex = sig_bytes.hex()
        display = sig_hex if len(sig_hex) <= 64 else sig_hex[:64] + "..."
    except Exception:
        display = signature

    print_section(f"SIGNATURE (hex, {len(sig_bytes)} bytes)", display, YELLOW)


if __name__ == "__main__":
    main()

代码只有 72 行，零依赖，直接拷贝即可运行。

小结

用 OpenCode 开发这个 JWT 解析工具，全程没有查一次文档、没有手动处理一次 base64url 的 padding 细节。三个步骤、三句自然语言描述，4 分钟得到一个完整可用的工具。

对比传统开发方式，你需要：查 JWT 格式规范 → 处理 Base64Url 变体 → 写 argparse → 处理异常 → 加 ANSI 颜色 → 格式化输出。每一步都可能因为不熟悉的细节而卡住。OpenCode 帮你跳过了所有这些"查文档、试错、修边角"的过程，让你专注于"我想要什么"而非"我该怎么写"。

这就是 AI 编程助手的真正价值——它不是一个自动补全工具，而是一个能理解你意图、帮你处理实现细节的编程搭档。