ice-jade 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68cefcd1f994be3fd223da84038c78ba39087227ac6ba22cfef06912b1e890d6
-  data.tar.gz: a5ee1b22d8929a592aa65a7725b94fdf2e2f63e071e202bd8e18ddf666410f59
+  metadata.gz: f57e6758c88b25a57a7891bed83b7416ae9f511e780bcde4be30bb6f211ee3b3
+  data.tar.gz: 902380ad3fb6f0bfd2bd21f171bc3aa99a9538590455ba4a41f2b582a8a0d326
 SHA512:
-  metadata.gz: 2fff58382ca71e712f1a7a21c23bb4465dee51789efc318aeae013af265d43ee43a5fc36f48cb8fc009069b28aff5fed42b90086696210a3424d1bd86d27fe20
-  data.tar.gz: 51fbc0b9a38a4e77da420c0f9c7464282940c643b173bbd106cb51e49e1f51dfbbcf85bbb313cc4bfda195f0cebf4422908412f453d91e0f1b4124cfe24010eb
+  metadata.gz: 14d027172321795ad155cc0cd3bbb8f196d18db00b20c9d51cb5c990c84184633bafffd637e7d50c10c1018e70319efc9b136de35b8e1bd364d112a84d79a10a
+  data.tar.gz: e7ddcc89ef4fde4cd0ee17f9ee81d03f4c7fec1f6c8a0c5329741bbf298d77422131c40b86dadb941b93ff6256409b80366c8fd3cd9fc6bac7601601841fc7ca

data/README.md

@@ -1,10 +1,23 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: '2bf760a7-7607-4806-8069-7ba5b57e6265'
+  PropagateID: '2bf760a7-7607-4806-8069-7ba5b57e6265'
+  ReservedCode1: '8dccec88-f08e-4a37-b7b8-a490337b1a1c'
+  ReservedCode2: '8dccec88-f08e-4a37-b7b8-a490337b1a1c'
+---
+
 # ice-jade
 
 ice-jade 是一个基于 Ruby 标准库的轻量级工具集，零外部依赖。最初定位是 IM Webhook SDK，现已扩展为包含多个独立分支的通用 HTTP 工具包：
 
 - **Quantum** — IM Webhook 客户端
 - **Poster** — 通用 HTTP POST 客户端
+- **Getter** — 通用 HTTP GET 客户端
 - **HttpPoster** — 独立模块级 HTTP POST 工具
+- **HttpGetter** — 独立模块级 HTTP GET 工具
 - **Cradle** — HTTP 测试服务器
 - **YAMLServer** — YAML 配置驱动的测试服务器实例
 
@@ -60,7 +73,7 @@ client.upload_and_send_file("/path/to/report.pdf")
 
 ## 分支二：Poster
 
-`IceJade::Poster::Client` 是通用 HTTP POST 客户端，面向对象设计，支持 JSON / Form / Multipart，内置超时重试和统一 `Response` 包装。
+`IceJade::Poster::Client` 是通用 HTTP POST 客户端，面向对象设计，支持 JSON / Form / Multipart，内置超时重试和统一 `Response` 包装。GET 请求请使用并列的 `IceJade::Getter::Client`。
 
 ### 快速开始
 
@@ -92,15 +105,43 @@ resp = poster.post('/hook', '<xml>...</xml>', content_type: 'application/xml')
 | 分支 | 定位 | 典型场景 |
 |------|------|----------|
 | Quantum | IM Webhook 专用 SDK | 向企业 IM 群机器人发消息 |
-| Poster | 通用 HTTP POST 客户端 | 调用任意 REST API、Webhook |
+| Poster | 通用 HTTP POST 客户端 | JSON/Form/Multipart 提交、Webhook、文件上传 |
+| Getter | 通用 HTTP GET 客户端 | 查询接口、健康检查、资源拉取 |
 
-两者共享 `IceJade::Response` 与 `IceJade::Error`，响应处理风格一致。
+三者共享 `IceJade::Transport`、`IceJade::Response` 与 `IceJade::Error`，响应处理风格一致。
 
-详细文档：`documents/poster-api.md`
+详细文档：`documents/poster-api.md`、`documents/getter-api.md`
 
 ---
 
-## 分支三：HttpPoster（独立模块）
+## 分支三：Getter
+
+`IceJade::Getter::Client` 是通用 HTTP GET 客户端，与 `Poster::Client` 并列，专责 GET 请求。底层传输能力（URI 拼接、超时重试、Response 包装）复用 `IceJade::Transport`，两者仅 HTTP 动词与参数构造不同。
+
+### 快速开始
+
+```ruby
+require 'ice_jade'
+
+getter = IceJade::Getter::Client.new(
+  base_url: 'https://api.example.com',
+  headers:  { 'Authorization' => 'Bearer token' },
+  timeout:  30
+)
+
+# GET 带查询参数
+resp = getter.get('/users', params: { page: 1, size: 20 })
+puts resp.data if resp.success?
+
+# GET 自定义请求头
+resp = getter.get('/headers', headers: { 'X-Request-ID' => 'uuid-5678' })
+```
+
+详细文档：`documents/getter-api.md`
+
+---
+
+## 分支四：HttpPoster（独立模块）
 
 `HttpPoster` 是 `lib/http_poster.rb` 中定义的纯标准库 HTTP POST 工具，零 gem 依赖。它是独立于 ice-jade gem 的扁平化脚本，适合不想引入任何 gem 的场景。
 
@@ -135,7 +176,47 @@ puts res  # => Hash（解析后的 JSON）
 
 ---
 
-## 分支四：Cradle（HTTP 测试服务器）
+## 分支五：HttpGetter（独立模块）
+
+`HttpGetter` 是 `lib/http_getter.rb` 中定义的纯标准库 HTTP GET 工具，零 gem 依赖。它与 `HttpPoster` 并列，构成独立的 POST / GET 工具对，适合不想引入任何 gem 的场景。
+
+### 快速开始
+
+```ruby
+require_relative 'lib/http_getter'
+
+# GET JSON（模块静态方法）
+res = HttpGetter.get_json(
+  'https://api.example.com/users',
+  { page: 1, size: 20 },
+  { 'Authorization' => 'Bearer token' },
+  { timeout: 30 }
+)
+puts res  # => Hash（解析后的 JSON）
+
+# GET 纯文本（不做 JSON 解析）
+text = HttpGetter.get_text('https://example.com/robots.txt')
+puts text  # => 原始字符串
+```
+
+### 与 Getter 的对比
+
+| 维度 | HttpGetter | IceJade::Getter::Client |
+|------|------------|-------------------------|
+| 调用方式 | 模块静态方法 | 先 `new` 实例化再调用 |
+| URL 处理 | 只能传完整 URL | 支持 `base_url` + 相对路径 |
+| 参数风格 | 位置参数 `(url,p,h,opts)` | 关键字参数 `(params:)` |
+| 成功返回 | Hash / String | `IceJade::Response` |
+| 错误处理 | 抛 `TimeoutError` / `HttpError` | 包装为 `Response`（不抛异常） |
+| 原始文本 | `get_text` 直接返回 String | 统一 Response（`data` 自动解析） |
+| 所属体系 | 独立脚本（无依赖） | ice-jade gem 分支 |
+| 典型场景 | 快速脚本、教学、零依赖 | 正式项目、与 Quantum 混用 |
+
+详细文档：`documents/http-getter-api.md`
+
+---
+
+## 分支六：Cradle（HTTP 测试服务器）
 
 Cradle 是轻量级 HTTP 测试服务器，基于 Ruby 标准库 `socket` + `thread`，零外部依赖。用于本地测试 Poster、Quantum 或其他 HTTP 客户端。
 
@@ -167,7 +248,7 @@ server.start
 
 ---
 
-## 分支五：YAMLServer（YAML 配置驱动的测试实例）
+## 分支七：YAMLServer（YAML 配置驱动的测试实例）
 
 YAMLServer 通过载入 YAML 配置文件启动定制化的 HTTP 测试实例，无需写 Ruby 代码注册路由，适合频繁切换测试场景。
 
@@ -222,17 +303,21 @@ Cradle 和 YAMLServer 都可以通过扩展代码添加新功能，变成满足
 ```
 lib/
   ice_jade.rb                  # 主入口
-  http_poster.rb               # 独立模块（零依赖）
+  http_poster.rb               # 独立 POST 模块（零依赖）
+  http_getter.rb               # 独立 GET 模块（零依赖）
   ice_jade/
     version.rb
     error.rb
     response.rb
     client_base.rb
+    transport.rb               # Poster/Getter 共享传输层
     quantum/
       client.rb
       message.rb
     poster/
-      client.rb
+      client.rb                # POST 客户端
+    getter/
+      client.rb                # GET 客户端
     cradle/
       server.rb               # 原生服务器
       yaml_server.rb          # YAML 配置层
@@ -247,13 +332,17 @@ config/cradle/
 examples/
   quantum_usage.rb            # Quantum 用法示例
   poster_usage.rb             # Poster + YAMLServer 联测
+  getter_usage.rb             # Getter + YAMLServer 联测
   comparison_poster.rb        # HttpPoster vs Poster 对比
+  comparison_getter.rb        # HttpGetter vs Getter 对比
   cradle_usage.rb             # Cradle 服务器用法
 
 documents/
   im-quantum-api.md           # Quantum API 文档
   poster-api.md               # Poster API 文档
+  getter-api.md               # Getter API 文档
   http-poster-api.md          # HttpPoster 文档
+  http-getter-api.md          # HttpGetter 文档
   cradle-api.md               # Cradle 文档
   yaml-server-api.md          # YAMLServer 文档
   cradle-extension.md         # 扩展指南
@@ -268,8 +357,10 @@ documents/
 ```
 ice-jade/
 ├── Quantum        # IM Webhook 客户端
-├── Poster         # 通用 HTTP POST 客户端
-├── HttpPoster     # 独立模块（零 gem 依赖）
+├── Poster         # 通用 HTTP POST 客户端  ┐
+├── Getter         # 通用 HTTP GET 客户端   ┤ 共享 Transport
+├── HttpPoster     # 独立 POST 模块（零 gem 依赖）  ┐
+├── HttpGetter     # 独立 GET 模块（零 gem 依赖）   ┘ 并列独立工具对
 ├── Cradle         # HTTP 测试服务器
 └── YAMLServer     # YAML 配置层（基于 Cradle）
 ```
@@ -322,3 +413,5 @@ end
 
 - Quantum：文件上传 30MB，消息频率 20条/分钟
 - Cradle：不支持 WebSocket、HTTPS、持久连接
+
+> AI生成

data/config/cradle/poster_test.yml

@@ -0,0 +1,41 @@
+# Cradle 实例配置：Poster 测试专用
+#
+# 启动命令:
+#   ruby bin/cradle-instance config/cradle/poster_test.yml
+#
+# 本配置为 IceJade::Poster 测试提供精确匹配的响应格式，
+# 使 examples/poster_usage.rb 和 examples/comparison_poster.rb 能够本地闭环通过。
+
+port: 8765
+host: 127.0.0.1
+
+routes:
+  # POST /echo —— 回显 JSON 请求体
+  - method: POST
+    path: /echo
+    handler: echo_json
+
+  # POST /form —— 回显 form-urlencoded 数据
+  - method: POST
+    path: /form
+    handler: echo_form
+
+  # POST /upload —— 回显 multipart 文件上传
+  - method: POST
+    path: /upload
+    handler: echo_upload
+
+  # POST /error —— 模拟 500 错误
+  - method: POST
+    path: /error
+    handler: static
+    status: 500
+    headers:
+      Content-Type: application/json
+    body: '{"error":"Internal Server Error"}'
+
+  # POST /delay/:seconds —— 延迟响应
+  - method: POST
+    path: /delay/:seconds
+    handler: delay
+    delay: 1

data/examples/comparison_getter.rb

@@ -0,0 +1,193 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# HttpGetter vs IceJade::Getter 同步对比示例
+# =============================================================================
+#
+# 本文件把两种调用方式并排展示，均面向本地 Cradle YAML 实例，
+# 通过 YAML 配置启动，无需外部网络，直接本地闭环验证。
+#
+# 左侧：HttpGetter —— 独立模块，静态方法，异常驱动
+# 右侧：IceJade::Getter —— 面向对象，实例化复用，Response 驱动
+#
+# =============================================================================
+
+require_relative '../lib/http_getter'
+require_relative '../lib/ice_jade'
+
+puts "=" * 70
+puts "HttpGetter (独立模块)  vs  IceJade::Getter (ice-jade gem 分支)"
+puts "目标: 本地 Cradle YAML 实例"
+puts "=" * 70
+
+# =============================================================================
+# 启动 Cradle YAML 实例
+# =============================================================================
+config_path = File.join(__dir__, '../config/cradle/poster_test.yml')
+instance = IceJade::Cradle::YAMLServer.new(config_path)
+thread = Thread.new { instance.start }
+sleep 0.5
+
+base_url = "http://#{instance.config['host']}:#{instance.config['port']}"
+
+# IceJade::Getter 实例（复用配置）
+getter = IceJade::Getter::Client.new(
+  base_url: base_url,
+  headers: { 'X-Custom-Header' => 'ice-jade' },
+  timeout: 30
+)
+
+begin
+
+  # ==========================================================================
+  # 场景 1：GET 查询参数回显
+  # ==========================================================================
+  puts "\n【场景 1】GET → /echo (查询参数)"
+  puts "-" * 70
+
+  # --- HttpGetter ---
+  begin
+    res = HttpGetter.get_json(
+      "#{base_url}/echo",
+      { page: 1, size: 20 },
+      { 'X-Custom-Header' => 'ice-jade' },
+      { timeout: 30 }
+    )
+    puts "[HttpGetter] Query echoed: #{res.is_a?(Hash) ? res['query'] : res}"
+  rescue HttpGetter::HttpError => e
+    puts "[HttpGetter] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Getter ---
+  resp = getter.get('/echo', params: { page: 1, size: 20 })
+  puts "[IceJade::Getter] Query echoed: #{resp.data.is_a?(Hash) ? resp.data['query'] : 'N/A'}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 场景 2：GET 自定义请求头回显
+  # ==========================================================================
+  puts "\n【场景 2】GET → /headers (自定义头)"
+  puts "-" * 70
+
+  # --- HttpGetter ---
+  begin
+    res = HttpGetter.get_json(
+      "#{base_url}/headers",
+      {},
+      { 'X-Custom-Header' => 'ice-jade', 'X-Request-ID' => 'uuid-5678' },
+      { timeout: 30 }
+    )
+    echoed = res.is_a?(Hash) ? res['headers'] : {}
+    puts "[HttpGetter] X-Custom-Header: #{echoed['X-Custom-Header']}"
+    puts "[HttpGetter] X-Request-Id: #{echoed['X-Request-Id']}"
+  rescue HttpGetter::HttpError => e
+    puts "[HttpGetter] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Getter ---
+  resp = getter.get('/headers', headers: { 'X-Request-ID' => 'uuid-5678' })
+  echoed = resp.data.is_a?(Hash) ? resp.data['headers'] : {}
+  puts "[IceJade::Getter] X-Custom-Header: #{echoed['X-Custom-Header']}"
+  puts "[IceJade::Getter] X-Request-Id: #{echoed['X-Request-Id']}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 场景 3：GET 纯文本（get_text 返回原始字符串，不做 JSON 解析）
+  # ==========================================================================
+  puts "\n【场景 3】GET 纯文本 → /echo (get_text)"
+  puts "-" * 70
+
+  # --- HttpGetter ---
+  begin
+    res = HttpGetter.get_text(
+      "#{base_url}/echo",
+      { ping: 'pong' },
+      {},
+      { timeout: 30 }
+    )
+    puts "[HttpGetter] 原始字符串: #{res.class} (#{res.to_s[0, 60]}...)"
+  rescue HttpGetter::HttpError => e
+    puts "[HttpGetter] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Getter ---
+  # Getter 没有 raw 选项，统一返回 Response，data 已解析
+  resp = getter.get('/echo', params: { ping: 'pong' })
+  puts "[IceJade::Getter] 解析后 data: #{resp.data.class}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 场景 4：错误处理（HTTP 404）
+  # ==========================================================================
+  puts "\n【场景 4】错误处理 → /status/404"
+  puts "-" * 70
+
+  # --- HttpGetter ---
+  begin
+    HttpGetter.get_json("#{base_url}/status/404", {}, {}, { timeout: 30 })
+  rescue HttpGetter::HttpError => e
+    puts "[HttpGetter] 捕获异常: #{e.message}"
+  end
+
+  # --- IceJade::Getter ---
+  resp = getter.get('/status/404')
+  puts "[IceJade::Getter] 不抛异常，直接检查响应:"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}, message: #{resp.message}"
+
+  # ==========================================================================
+  # 场景 5：通用 get（url 已含 query，params 追加）
+  # ==========================================================================
+  puts "\n【场景 5】通用 get → /echo?foo=1 (params 追加)"
+  puts "-" * 70
+
+  # --- HttpGetter ---
+  begin
+    res = HttpGetter.get(
+      "#{base_url}/echo?foo=1",
+      { bar: '2' },
+      { 'X-Request-ID' => 'uuid-1234' },
+      { timeout: 30 }
+    )
+    puts "[HttpGetter] Query echoed: #{res.is_a?(Hash) ? res['query'] : res}"
+  rescue HttpGetter::HttpError => e
+    puts "[HttpGetter] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Getter ---
+  resp = getter.get('/echo?foo=1', params: { bar: '2' },
+                    headers: { 'X-Request-ID' => 'uuid-1234' })
+  puts "[IceJade::Getter] Query echoed: #{resp.data.is_a?(Hash) ? resp.data['query'] : 'N/A'}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 结构差异速查表
+  # ==========================================================================
+  puts "\n" + "=" * 70
+  puts "结构差异速查表"
+  puts "=" * 70
+  puts <<~DIFF
+
+    ┌──────────────────┬──────────────────────────┬──────────────────────────┐
+    │     维度         │      HttpGetter          │    IceJade::Getter       │
+    ├──────────────────┼──────────────────────────┼──────────────────────────┤
+    │ 调用方式         │ 模块静态方法             │ 先 new 实例化再调用      │
+    │ URL 处理         │ 只能传完整 URL           │ 支持 base_url + 相对路径 │
+    │ 参数风格         │ 位置参数 (url,p,h,opts)  │ 关键字参数 (params:)     │
+    │ 配置复用         │ 每次调用都传 headers     │ 初始化一次，多次复用     │
+    │ 成功返回         │ Hash / String            │ IceJade::Response        │
+    │ 错误处理         │ 抛 TimeoutError/HttpError│ 包装为 Response          │
+    │ 判断结果         │ begin/rescue             │ resp.success?            │
+    │ 原始文本         │ get_text 直接返回 String │ 统一 Response（data 解析）│
+    │ 所属体系         │ 独立脚本                 │ ice-jade gem 分支        │
+    │ 适合场景         │ 快速脚本、教学、零依赖   │ 正式项目、与 Quantum 混用│
+    └──────────────────┴──────────────────────────┴──────────────────────────┘
+
+  DIFF
+  puts "示例运行完毕。"
+
+ensure
+  instance.stop
+  thread.join
+  puts "\nCradle YAML 实例已关闭。"
+end

data/examples/comparison_poster.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# HttpPoster vs IceJade::Poster 同步对比示例
+# =============================================================================
+#
+# 本文件把两种调用方式并排展示，均面向本地 Cradle YAML 实例，
+# 通过 YAML 配置启动，无需外部网络，直接本地闭环验证。
+#
+# 左侧：HttpPoster —— 独立模块，静态方法，异常驱动
+# 右侧：IceJade::Poster —— 面向对象，实例化复用，Response 驱动
+#
+# =============================================================================
+
+require_relative '../lib/http_poster'
+require_relative '../lib/ice_jade'
+require 'tmpdir'
+
+puts "=" * 70
+puts "HttpPoster (独立模块)  vs  IceJade::Poster (ice-jade gem 分支)"
+puts "目标: 本地 Cradle YAML 实例"
+puts "=" * 70
+
+# =============================================================================
+# 启动 Cradle YAML 实例
+# =============================================================================
+config_path = File.join(__dir__, '../config/cradle/poster_test.yml')
+instance = IceJade::Cradle::YAMLServer.new(config_path)
+thread = Thread.new { instance.start }
+sleep 0.5
+
+base_url = "http://#{instance.config['host']}:#{instance.config['port']}"
+
+# IceJade::Poster 实例（复用配置）
+poster = IceJade::Poster::Client.new(
+  base_url: base_url,
+  headers: { 'X-Custom-Header' => 'ice-jade' },
+  timeout: 30
+)
+
+begin
+
+  # ==========================================================================
+  # 场景 1：POST JSON
+  # ==========================================================================
+  puts "\n【场景 1】POST JSON → /echo"
+  puts "-" * 70
+
+  # --- HttpPoster ---
+  begin
+    res = HttpPoster.post_json(
+      "#{base_url}/echo",
+      { name: 'Alice', role: 'admin' },
+      { 'X-Custom-Header' => 'ice-jade' },
+      { timeout: 30 }
+    )
+    puts "[HttpPoster] Echo body: #{res.is_a?(Hash) ? res['body'] : res}"
+  rescue HttpPoster::HttpError => e
+    puts "[HttpPoster] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Poster ---
+  resp = poster.post_json('/echo', { name: 'Alice', role: 'admin' })
+  puts "[IceJade::Poster] Echo body: #{resp.data.is_a?(Hash) ? resp.data['body'] : resp.data}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 场景 2：POST Form
+  # ==========================================================================
+  puts "\n【场景 2】POST Form → /form"
+  puts "-" * 70
+
+  # --- HttpPoster ---
+  begin
+    res = HttpPoster.post_form(
+      "#{base_url}/form",
+      { username: 'admin', password: 'secret' },
+      {},
+      { timeout: 30 }
+    )
+    puts "[HttpPoster] Form echoed: #{res.is_a?(Hash) ? res['form'] : res}"
+  rescue HttpPoster::HttpError => e
+    puts "[HttpPoster] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Poster ---
+  resp = poster.post_form('/form', { username: 'admin', password: 'secret' })
+  puts "[IceJade::Poster] Form echoed: #{resp.data.is_a?(Hash) ? resp.data['form'] : 'N/A'}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 场景 3：POST Multipart（文件上传）
+  # ==========================================================================
+  puts "\n【场景 3】POST Multipart → /upload"
+  puts "-" * 70
+
+  tmp_path = File.join(Dir.tmpdir, 'ice_jade_demo.txt')
+  File.write(tmp_path, "Hello from IceJade!\n")
+
+  # --- HttpPoster ---
+  begin
+    res = HttpPoster.post_multipart(
+      "#{base_url}/upload",
+      { file: tmp_path, description: 'demo' },
+      {},
+      { timeout: 30 }
+    )
+    puts "[HttpPoster] 文件名回显: #{res.is_a?(Hash) ? res['files']&.keys : res}"
+  rescue HttpPoster::HttpError => e
+    puts "[HttpPoster] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Poster ---
+  resp = poster.post_multipart('/upload', { file: tmp_path, description: 'demo' })
+  puts "[IceJade::Poster] 文件名回显: #{resp.data.is_a?(Hash) ? resp.data['files']&.keys : 'N/A'}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  File.delete(tmp_path)
+
+  # ==========================================================================
+  # 场景 4：错误处理（HTTP 500）
+  # ==========================================================================
+  puts "\n【场景 4】错误处理 → /error"
+  puts "-" * 70
+
+  # --- HttpPoster ---
+  begin
+    HttpPoster.post_json("#{base_url}/error", {})
+  rescue HttpPoster::HttpError => e
+    puts "[HttpPoster] 捕获异常: #{e.message}"
+  end
+
+  # --- IceJade::Poster ---
+  resp = poster.post_json('/error', {})
+  puts "[IceJade::Poster] 不抛异常，直接检查响应:"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}, message: #{resp.message}"
+
+  # ==========================================================================
+  # 场景 5：通用 post（自定义 Content-Type）
+  # ==========================================================================
+  puts "\n【场景 5】通用 post → /echo (application/xml)"
+  puts "-" * 70
+
+  # --- HttpPoster ---
+  begin
+    res = HttpPoster.post(
+      "#{base_url}/echo",
+      '<xml><body>hello</body></xml>',
+      { 'Content-Type' => 'application/xml',
+        'X-Request-ID' => 'uuid-1234' },
+      { timeout: 30 }
+    )
+    puts "[HttpPoster] Content-Type 回显: #{res.is_a?(Hash) ? res['headers']&.dig('Content-Type') : res}"
+  rescue HttpPoster::HttpError => e
+    puts "[HttpPoster] 失败: #{e.message}"
+  end
+
+  # --- IceJade::Poster ---
+  resp = poster.post('/echo', '<xml><body>hello</body></xml>',
+                     headers: { 'X-Request-ID' => 'uuid-1234' },
+                     content_type: 'application/xml')
+  puts "[IceJade::Poster] Content-Type 回显: #{resp.data.is_a?(Hash) ? resp.data['headers']&.dig('Content-Type') : 'N/A'}"
+  puts "                  success?: #{resp.success?}, code: #{resp.code}"
+
+  # ==========================================================================
+  # 结构差异速查表
+  # ==========================================================================
+  puts "\n" + "=" * 70
+  puts "结构差异速查表"
+  puts "=" * 70
+  puts <<~DIFF
+
+    ┌──────────────────┬──────────────────────────┬──────────────────────────┐
+    │     维度         │      HttpPoster          │    IceJade::Poster       │
+    ├──────────────────┼──────────────────────────┼──────────────────────────┤
+    │ 调用方式         │ 模块静态方法             │ 先 new 实例化再调用      │
+    │ URL 处理         │ 只能传完整 URL           │ 支持 base_url + 相对路径 │
+    │ 参数风格         │ 位置参数 (url,p,h,opts)  │ 关键字参数 (headers:)    │
+    │ 配置复用         │ 每次调用都传 headers     │ 初始化一次，多次复用     │
+    │ 成功返回         │ Hash / String            │ IceJade::Response        │
+    │ 错误处理         │ 抛 TimeoutError/HttpError│ 包装为 Response          │
+    │ 判断结果         │ begin/rescue             │ resp.success?            │
+    │ 所属体系         │ 独立脚本                 │ ice-jade gem 分支        │
+    │ 适合场景         │ 快速脚本、教学、零依赖   │ 正式项目、与 Quantum 混用│
+    └──────────────────┴──────────────────────────┴──────────────────────────┘
+
+  DIFF
+  puts "示例运行完毕。"
+
+ensure
+  instance.stop
+  thread.join
+  puts "\nCradle YAML 实例已关闭。"
+end