ice-jade 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70f058625ea166e107bf454a437142ebb6a4cb0f3c49d88e484fe45be069d271
-  data.tar.gz: 0ea0b70756e261510b7ac062f39f02411dd7a54301b7f3c86339c7f6380f57db
+  metadata.gz: f57e6758c88b25a57a7891bed83b7416ae9f511e780bcde4be30bb6f211ee3b3
+  data.tar.gz: 902380ad3fb6f0bfd2bd21f171bc3aa99a9538590455ba4a41f2b582a8a0d326
 SHA512:
-  metadata.gz: aed37f531cce690f2ed41b80adcc5e45b8a7cab2dbb5ad1c4c2c111d4e477ae9c8e172a99f02b05a1ca13a4a150169e23c2f00109f49ec0dd640338e232eb6c1
-  data.tar.gz: 72cc6594677d28a1ea49ef7f9fac87dd73ff8af30ce1af9dac8fa3c95740171aab185b3c0b5b1f2f418e87b938dd38900c1b27ceea5adfec022c2ba76a77c874
+  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/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/getter_usage.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Getter 用法示例：调用 Cradle YAML 实例
+#
+# 本示例通过 YAML 配置启动定制化的 Cradle 测试实例，
+# 然后用 IceJade::Getter::Client 向它发起 GET 请求，本地闭环验证。
+#
+# Getter 与 Poster 并列：Poster 专责 POST，Getter 专责 GET，
+# 两者复用同一套 IceJade::Transport 底层（URI 拼接、超时重试、Response 包装）。
+
+require_relative '../lib/ice_jade'
+
+# =============================================================================
+# 1. 启动 Cradle YAML 实例
+# =============================================================================
+puts "=== 启动 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
+
+getter = IceJade::Getter::Client.new(
+  base_url: "http://#{instance.config['host']}:#{instance.config['port']}",
+  headers: { 'X-Custom-Header' => 'ice-jade' }
+)
+
+begin
+
+  # ------------------------------------------------------------------
+  # 1. GET 查询参数回显
+  # ------------------------------------------------------------------
+  puts "\n=== 1. GET → /echo (查询参数) ==="
+  resp = getter.get('/echo', params: { page: 1, size: 20 })
+  puts "Success: #{resp.success?}, Code: #{resp.code}, Message: #{resp.message}"
+  puts "Query echoed: #{resp.data.is_a?(Hash) ? resp.data['query'] : 'N/A'}"
+
+  # ------------------------------------------------------------------
+  # 2. GET 回显请求头（默认头 + 额外头合并校验）
+  # ------------------------------------------------------------------
+  puts "\n=== 2. GET → /headers (自定义头) ==="
+  resp = getter.get('/headers', headers: { 'X-Request-ID' => 'uuid-5678' })
+  puts "Success: #{resp.success?}, Code: #{resp.code}"
+  # 注意：Net::HTTP 会将头名规范化为 X-Request-Id（每段首字母大写）
+  echoed_headers = resp.data.is_a?(Hash) ? resp.data['headers'] : {}
+  puts "X-Custom-Header: #{echoed_headers['X-Custom-Header']}"
+  puts "X-Request-Id: #{echoed_headers['X-Request-Id']}"
+
+  # ------------------------------------------------------------------
+  # 3. GET 错误处理（HTTP 404）
+  # ------------------------------------------------------------------
+  puts "\n=== 3. GET 错误处理 → /status/404 ==="
+  resp = getter.get('/status/404')
+  puts "Success: #{resp.success?}, Code: #{resp.code}, Message: #{resp.message}"
+
+  # ------------------------------------------------------------------
+  # 4. GET 错误处理（HTTP 500）
+  # ------------------------------------------------------------------
+  puts "\n=== 4. GET 错误处理 → /status/500 ==="
+  resp = getter.get('/status/500')
+  puts "Success: #{resp.success?}, Code: #{resp.code}, Message: #{resp.message}"
+
+  # ------------------------------------------------------------------
+  # 5. GET 已含 query 的 URL（params 追加而非覆盖）
+  # ------------------------------------------------------------------
+  puts "\n=== 5. GET → /echo?foo=1 (params 追加) ==="
+  resp = getter.get('/echo?foo=1', params: { bar: '2' })
+  puts "Success: #{resp.success?}, Code: #{resp.code}"
+  puts "Query echoed: #{resp.data.is_a?(Hash) ? resp.data['query'] : 'N/A'}"
+
+  # ------------------------------------------------------------------
+  # 6. GET 健康检查
+  # ------------------------------------------------------------------
+  puts "\n=== 6. GET → /health ==="
+  resp = getter.get('/health')
+  puts "Success: #{resp.success?}, Code: #{resp.code}"
+  puts "Status: #{resp.data.is_a?(Hash) ? resp.data['status'] : 'N/A'}"
+
+  puts "\n=== 所有测试通过 ==="
+
+ensure
+  instance.stop
+  thread.join
+  puts "\nCradle YAML 实例已关闭。"
+end

data/lib/http_getter.rb

@@ -0,0 +1,159 @@
+# http_getter.rb
+# Ruby 纯标准库 HTTP GET 工具模块
+# 零外部依赖，支持查询参数 / JSON / 透传响应
+#
+# =============================================================================
+# 说明：本模块是独立工具脚本，不依赖 ice-jade gem。
+#
+#   如果你正在使用 ice-jade 项目，推荐优先使用 IceJade::Getter::Client
+#   （位于 lib/ice_jade/getter/client.rb），原因：
+#
+#   - 面向对象：初始化时配置 base_url/headers/timeout，后续复用
+#   - 统一响应：返回 IceJade::Response（ok, code, message, data, raw）
+#   - 异常友好：超时/HTTP 错误均包装为 Response，不抛异常
+#   - 与 Quantum 分支共享同一套响应体系
+#
+#   HttpGetter 适合：
+#   - 不想引入任何 gem 依赖的独立脚本
+#   - 快速测试、一次性请求
+#   - 学习/教学用途，代码更扁平直观
+#
+#   对比示例见：examples/comparison_getter.rb
+# =============================================================================
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module HttpGetter
+  class Error < StandardError; end
+  class TimeoutError < Error; end
+  class HttpError < Error; end
+
+  # ============ 核心 GET 方法 ============
+  #
+  # @param url      [String]  完整 URL 或路径；若已含 query，params 会追加在其后
+  # @param params   [Hash]    查询参数，自动用 URI.encode_www_form 编码到 query string
+  # @param headers  [Hash]    自定义请求头（自动覆盖默认头）
+  # @param opts     [Hash]    选项: :timeout, :open_timeout, :max_retries
+  #
+  # @return [Hash/String] 解析后的 JSON 或原始响应体
+  #
+  def self.get(url, params = {}, headers = {}, opts = {})
+    uri = URI.parse(url)
+    unless params.empty?
+      extra = URI.encode_www_form(params)
+      uri.query = uri.query ? "#{uri.query}&#{extra}" : extra
+    end
+
+    req = Net::HTTP::Get.new(uri)
+    req['User-Agent'] = headers['User-Agent'] || 'ruby-http-getter/1.0'
+    req['Accept'] = headers['Accept'] || 'application/json'
+
+    # 认证头（支持 Bearer Token）
+    if headers['Authorization'] || headers[:authorization]
+      req['Authorization'] = headers['Authorization'] || headers[:authorization]
+    end
+
+    # 追加其余自定义头
+    headers.each do |k, v|
+      next if %w[Accept Authorization User-Agent].include?(k.to_s)
+      req[k.to_s] = v.to_s
+    end
+
+    execute(uri, req, opts)
+  end
+
+  # ============ 快捷方法 ============
+
+  # GET JSON（API 调用最常用）
+  # 自动设置 Accept: application/json，期望服务端返回 JSON
+  def self.get_json(url, params = {}, headers = {}, opts = {})
+    headers = headers.merge('Accept' => 'application/json')
+    get(url, params, headers, opts)
+  end
+
+  # GET 纯文本（原始响应体，不做 JSON 解析）
+  # 自动设置 Accept: text/plain，返回原始 String
+  def self.get_text(url, params = {}, headers = {}, opts = {})
+    headers = headers.merge('Accept' => 'text/plain')
+    opts = opts.merge(__raw__: true)
+    get(url, params, headers, opts)
+  end
+
+  private
+
+  def self.execute(uri, request, opts = {})
+    timeout = opts[:timeout] || 60
+    open_timeout = opts[:open_timeout] || 10
+    max_retries = opts[:max_retries] || 2
+    raw = opts[:__raw__] == true
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.open_timeout = open_timeout
+    http.read_timeout = timeout
+
+    retries = 0
+    begin
+      response = http.request(request)
+      parse(response, raw)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      retries += 1
+      if retries <= max_retries
+        sleep(2 ** retries)
+        retry
+      end
+      raise TimeoutError, "请求超时（已重试 #{max_retries} 次）: #{e.message}"
+    ensure
+      http.finish if http.started?
+    end
+  end
+
+  def self.parse(response, raw = false)
+    body = response.body.to_s
+    code = response.code.to_i
+
+    if code >= 400
+      begin
+        err = JSON.parse(body)
+        msg = err.dig('error', 'message') || body
+      rescue
+        msg = body
+      end
+      raise HttpError, "HTTP #{code}: #{msg}"
+    end
+
+    return body if raw
+
+    JSON.parse(body) rescue body
+  end
+end
+
+# ============ 使用示例 ============
+if __FILE__ == $0
+  # 示例 1: GET JSON（调用公开 API）
+  begin
+    res = HttpGetter.get_json(
+      'https://httpbin.org/get',
+      { page: 1, size: 20 },
+      { 'Authorization' => 'Bearer your-token-here' },
+      { timeout: 30 }
+    )
+    puts res['args']
+  rescue HttpGetter::HttpError => e
+    puts "请求失败: #{e.message}"
+  end
+
+  # 示例 2: GET 纯文本
+  # res = HttpGetter.get_text('https://httpbin.org/robots.txt')
+  # puts res  # => 原始字符串
+
+  # 示例 3: 通用 GET（自定义头，url 已含 query，params 追加）
+  # res = HttpGetter.get(
+  #   'https://httpbin.org/get?foo=1',
+  #   { bar: '2' },
+  #   { 'X-Request-ID' => 'uuid-5678' }
+  # )
+  # puts res['args']  # => {"foo"=>"1", "bar"=>"2"}
+end

data/lib/ice_jade/getter/client.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative '../transport'
+
+module IceJade
+  module Getter
+    # 通用 HTTP GET 客户端
+    #
+    # 与 IceJade::Poster::Client 并列，专用负责 GET 请求。
+    # 底层传输能力（URI 拼接、请求执行、响应适配、超时重试）复用 IceJade::Transport，
+    # 与 Poster 仅 HTTP 动词与参数构造不同：GET 幂等，无请求体，参数走 query string。
+    #
+    # 零外部依赖，内置超时控制、指数退避重试、统一 Response 包装，
+    # 与 Quantum 模块风格一致，错误不抛异常。
+    #
+    # @example 基础用法
+    #   getter = IceJade::Getter::Client.new(
+    #     base_url: 'https://api.example.com',
+    #     headers:  { 'Authorization' => 'Bearer token' },
+    #     timeout:  30
+    #   )
+    #   resp = getter.get('/users', params: { page: 1, size: 20 })
+    #   puts resp.data if resp.success?
+    #
+    class Client
+      include IceJade::Transport
+
+      # @param base_url     [String, nil] 基础 URL，后续请求可传相对路径
+      # @param headers      [Hash] 默认请求头（每次请求自动合并，同名会被覆盖）
+      # @param timeout      [Integer] 读取超时（秒），默认 60
+      # @param open_timeout [Integer] 连接超时（秒），默认 10
+      # @param max_retries  [Integer] 超时后最大重试次数，默认 2
+      def initialize(base_url: nil, headers: {}, timeout: 60, open_timeout: 10, max_retries: 2)
+        init_transport(base_url: base_url, headers: headers,
+                       timeout: timeout, open_timeout: open_timeout,
+                       max_retries: max_retries)
+      end
+
+      # ------------------------------------------------------------------
+      # 通用 GET
+      # ------------------------------------------------------------------
+
+      # 发送通用 GET 请求
+      #
+      # 与 Poster 的 post 系列方法对称：返回 IceJade::Response，错误不抛异常。
+      # GET 幂等，超时重试同样安全。
+      #
+      # @param url     [String] 完整 URL 或相对路径（需先设置 base_url）
+      # @param params  [Hash, nil] 查询参数，自动用 URI.encode_www_form 编码到 query string；
+      #                若 url 已含 query，则在其后追加
+      # @param headers [Hash] 额外请求头（与默认头合并，同名覆盖）
+      # @return [IceJade::Response]
+      #
+      # @example 带查询参数
+      #   resp = getter.get('/users', params: { page: 1, size: 20 })
+      #   puts resp.data if resp.success?
+      #
+      # @example 自定义请求头
+      #   resp = getter.get('/headers', headers: { 'X-Request-ID' => 'uuid-5678' })
+      #
+      # @example 错误响应
+      #   resp = getter.get('/status/404')
+      #   resp.success?  # => false
+      #   resp.code      # => 404
+      def get(url, params: nil, headers: {})
+        uri = build_uri(url)
+        if params && !params.empty?
+          extra = URI.encode_www_form(params)
+          uri.query = uri.query ? "#{uri.query}&#{extra}" : extra
+        end
+        merged_headers = merge_headers(default_headers, normalize_headers(headers))
+        req = Net::HTTP::Get.new(uri)
+        apply_headers(req, merged_headers)
+        execute(uri, req)
+      end
+    end
+  end
+end

data/lib/ice_jade/getter.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'getter/client'

data/lib/ice_jade/poster/client.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'uri'
-require 'securerandom'
-require_relative '../response'
-require_relative '../error'
+require_relative '../transport'
 
 module IceJade
   module Poster
@@ -13,6 +8,7 @@ module IceJade
     #
     # 零外部依赖，支持 JSON / Form / Multipart 三种常用提交方式，
     # 内置超时控制、指数退避重试、统一 Response 包装，与 Quantum 模块风格一致。
+    # 底层传输能力（URI 拼接、请求执行、响应适配、超时重试）复用 IceJade::Transport，
     #
     # @example 基础用法
     #   poster = IceJade::Poster::Client.new(
@@ -24,7 +20,7 @@ module IceJade
     #   puts resp.data if resp.success?
     #
     class Client
-      attr_reader :base_url, :default_headers, :timeout, :open_timeout, :max_retries
+      include IceJade::Transport
 
       # @param base_url     [String, nil] 基础 URL，后续请求可传相对路径
       # @param headers      [Hash] 默认请求头（每次请求自动合并，同名会被覆盖）
@@ -32,11 +28,9 @@ module IceJade
       # @param open_timeout [Integer] 连接超时（秒），默认 10
       # @param max_retries  [Integer] 超时后最大重试次数，默认 2
       def initialize(base_url: nil, headers: {}, timeout: 60, open_timeout: 10, max_retries: 2)
-        @base_url = base_url ? base_url.to_s.chomp('/') : nil
-        @default_headers = normalize_headers(headers)
-        @timeout = timeout
-        @open_timeout = open_timeout
-        @max_retries = max_retries
+        init_transport(base_url: base_url, headers: headers,
+                       timeout: timeout, open_timeout: open_timeout,
+                       max_retries: max_retries)
       end
 
       # ------------------------------------------------------------------
@@ -101,14 +95,7 @@ module IceJade
 
       private
 
-      def build_uri(url)
-        if base_url && !url.to_s.start_with?('http')
-          URI.parse("#{base_url}#{url}")
-        else
-          URI.parse(url.to_s)
-        end
-      end
-
+      # 构造 POST 请求对象（JSON / Form / 自定义 Content-Type 三种序列化分支）
       def build_request(uri, body, content_type, headers)
         req = Net::HTTP::Post.new(uri)
         apply_headers(req, headers)
@@ -127,122 +114,6 @@ module IceJade
 
         req
       end
-
-      def apply_headers(req, headers)
-        headers.each do |k, v|
-          req[k.to_s] = v.to_s
-        end
-      end
-
-      def normalize_headers(h)
-        h.transform_keys(&:to_s).transform_values(&:to_s)
-      end
-
-      def merge_headers(base, extra)
-        base.merge(extra)
-      end
-
-      def execute(uri, request)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == 'https'
-        http.open_timeout = open_timeout
-        http.read_timeout = timeout
-
-        retries = 0
-        begin
-          response = http.request(request)
-          Response.new(adapt_response(response))
-        rescue Net::OpenTimeout, Net::ReadTimeout => e
-          retries += 1
-          if retries <= max_retries
-            sleep(2**retries)
-            retry
-          end
-          Response.new({ 'ok' => false, 'code' => 0,
-                         'message' => "Timeout after #{max_retries} retries: #{e.message}", 'data' => nil })
-        rescue StandardError => e
-          Response.new({ 'ok' => false, 'code' => 0, 'message' => e.message, 'data' => nil })
-        ensure
-          http.finish if http.started?
-        end
-      end
-
-      # 内置 HTTP 状态码文本（兼容各 Ruby 版本）
-      HTTP_STATUS_TEXT = {
-        100 => 'Continue', 101 => 'Switching Protocols',
-        200 => 'OK', 201 => 'Created', 202 => 'Accepted',
-        204 => 'No Content',
-        301 => 'Moved Permanently', 302 => 'Found', 304 => 'Not Modified',
-        400 => 'Bad Request', 401 => 'Unauthorized', 403 => 'Forbidden',
-        404 => 'Not Found', 405 => 'Method Not Allowed',
-        429 => 'Too Many Requests',
-        500 => 'Internal Server Error', 502 => 'Bad Gateway',
-        503 => 'Service Unavailable'
-      }.freeze
-
-      def adapt_response(response)
-        body = response.body.to_s
-        code = response.code.to_i
-
-        data = begin
-                 JSON.parse(body)
-               rescue JSON::ParserError
-                 body
-               end
-
-        {
-          'ok' => code >= 200 && code < 300,
-          'code' => code,
-          'message' => HTTP_STATUS_TEXT[code] || 'Unknown',
-          'data' => data
-        }
-      end
-
-      def build_multipart(params)
-        boundary = "----IceJadePosterBoundary#{SecureRandom.hex(16)}"
-        body = +"".b
-
-        params.each do |key, value|
-          if value.is_a?(String) && File.exist?(value)
-            filename = File.basename(value)
-            file_data = File.binread(value)
-            mime = mime_type(filename)
-            body << "--#{boundary}\r\n"
-            body << %(Content-Disposition: form-data; name="#{key}"; filename="#{filename}") << "\r\n"
-            body << "Content-Type: #{mime}" << "\r\n\r\n"
-            body << file_data.b
-            body << "\r\n"
-          else
-            body << "--#{boundary}\r\n"
-            body << %(Content-Disposition: form-data; name="#{key}") << "\r\n\r\n"
-            body << value.to_s
-            body << "\r\n"
-          end
-        end
-
-        body << "--#{boundary}--\r\n"
-        [body, boundary]
-      end
-
-      def mime_type(filename)
-        ext = File.extname(filename).downcase
-        case ext
-        when '.png'            then 'image/png'
-        when '.jpg', '.jpeg'   then 'image/jpeg'
-        when '.gif'            then 'image/gif'
-        when '.webp'           then 'image/webp'
-        when '.bmp'            then 'image/bmp'
-        when '.pdf'            then 'application/pdf'
-        when '.txt'            then 'text/plain'
-        when '.json'           then 'application/json'
-        when '.zip'            then 'application/zip'
-        when '.doc'            then 'application/msword'
-        when '.docx'           then 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-        when '.xls'            then 'application/vnd.ms-excel'
-        when '.xlsx'           then 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
-        else                        'application/octet-stream'
-        end
-      end
     end
   end
 end

data/lib/ice_jade/transport.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'securerandom'
+require_relative 'response'
+require_relative 'error'
+
+module IceJade
+  # HTTP 传输层共享逻辑
+  #
+  # Poster::Client 与 Getter::Client 共用的底层能力：
+  # base_url 拼接、默认头合并、Net::HTTP 执行、超时指数退避重试、
+  # 状态码/JSON 解析/Response 包装。
+  #
+  # 设计为 instance 方法模块，由两个 Client 类 include 后复用，
+  # 各自只关心自己负责的 HTTP 动词与参数构造，传输细节由 Transport 统一。
+  module Transport
+    # 公共初始化参数解析，供两个 Client 的 #initialize 调用
+    #
+    # @param base_url     [String, nil] 基础 URL，后续请求可传相对路径
+    # @param headers      [Hash] 默认请求头（每次请求自动合并，同名会被覆盖）
+    # @param timeout      [Integer] 读取超时（秒）
+    # @param open_timeout [Integer] 连接超时（秒）
+    # @param max_retries  [Integer] 超时后最大重试次数
+    def init_transport(base_url:, headers:, timeout:, open_timeout:, max_retries:)
+      @base_url = base_url ? base_url.to_s.chomp('/') : nil
+      @default_headers = normalize_headers(headers)
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @max_retries = max_retries
+    end
+
+    attr_reader :base_url, :default_headers, :timeout, :open_timeout, :max_retries
+
+    # 拼接 base_url 与相对路径，或直接解析完整 URL
+    #
+    # @param url [String] 完整 URL 或相对路径（需先设置 base_url）
+    # @return [URI::Generic]
+    def build_uri(url)
+      if base_url && !url.to_s.start_with?('http')
+        URI.parse("#{base_url}#{url}")
+      else
+        URI.parse(url.to_s)
+      end
+    end
+
+    # 将头 Hash 写入 Net::HTTP 请求对象
+    def apply_headers(req, headers)
+      headers.each do |k, v|
+        req[k.to_s] = v.to_s
+      end
+    end
+
+    # 头键值统一字符串化
+    def normalize_headers(h)
+      h.transform_keys(&:to_s).transform_values(&:to_s)
+    end
+
+    # 默认头与额外头合并（额外同名覆盖）
+    def merge_headers(base, extra)
+      base.merge(extra)
+    end
+
+    # 执行 Net::HTTP 请求，超时指数退避重试，异常包装为 Response
+    #
+    # @param uri     [URI::Generic]
+    # @param request [Net::HTTPGenericRequest]
+    # @return [IceJade::Response]
+    def execute(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = open_timeout
+      http.read_timeout = timeout
+
+      retries = 0
+      begin
+        response = http.request(request)
+        Response.new(adapt_response(response))
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        retries += 1
+        if retries <= max_retries
+          sleep(2**retries)
+          retry
+        end
+        Response.new({ 'ok' => false, 'code' => 0,
+                       'message' => "Timeout after #{max_retries} retries: #{e.message}", 'data' => nil })
+      rescue StandardError => e
+        Response.new({ 'ok' => false, 'code' => 0, 'message' => e.message, 'data' => nil })
+      ensure
+        http.finish if http.started?
+      end
+    end
+
+    # 内置 HTTP 状态码文本（兼容各 Ruby 版本）
+    HTTP_STATUS_TEXT = {
+      100 => 'Continue', 101 => 'Switching Protocols',
+      200 => 'OK', 201 => 'Created', 202 => 'Accepted',
+      204 => 'No Content',
+      301 => 'Moved Permanently', 302 => 'Found', 304 => 'Not Modified',
+      400 => 'Bad Request', 401 => 'Unauthorized', 403 => 'Forbidden',
+      404 => 'Not Found', 405 => 'Method Not Allowed',
+      429 => 'Too Many Requests',
+      500 => 'Internal Server Error', 502 => 'Bad Gateway',
+      503 => 'Service Unavailable'
+    }.freeze
+
+    # 将 Net::HTTP 响应适配为 IceJade::Response 所需的 Hash
+    #
+    # @param response [Net::HTTPResponse]
+    # @return [Hash] 形如 { 'ok' => bool, 'code' => int, 'message' => str, 'data' => data }
+    def adapt_response(response)
+      body = response.body.to_s
+      code = response.code.to_i
+
+      data = begin
+               JSON.parse(body)
+             rescue JSON::ParserError
+               body
+             end
+
+      {
+        'ok' => code >= 200 && code < 300,
+        'code' => code,
+        'message' => HTTP_STATUS_TEXT[code] || 'Unknown',
+        'data' => data
+      }
+    end
+
+    # multipart 边界生成与 MIME 推断 —— POST 专用，Getter 不使用，
+    # 但为保持 Transport 的自包含性一并放在这里，供 Poster::Client 复用。
+    def build_multipart(params)
+      boundary = "----IceJadeTransportBoundary#{SecureRandom.hex(16)}"
+      body = +"".b
+
+      params.each do |key, value|
+        if value.is_a?(String) && File.exist?(value)
+          filename = File.basename(value)
+          file_data = File.binread(value)
+          mime = mime_type(filename)
+          body << "--#{boundary}\r\n"
+          body << %(Content-Disposition: form-data; name="#{key}"; filename="#{filename}") << "\r\n"
+          body << "Content-Type: #{mime}" << "\r\n\r\n"
+          body << file_data.b
+          body << "\r\n"
+        else
+          body << "--#{boundary}\r\n"
+          body << %(Content-Disposition: form-data; name="#{key}") << "\r\n\r\n"
+          body << value.to_s
+          body << "\r\n"
+        end
+      end
+
+      body << "--#{boundary}--\r\n"
+      [body, boundary]
+    end
+
+    def mime_type(filename)
+      ext = File.extname(filename).downcase
+      case ext
+      when '.png'            then 'image/png'
+      when '.jpg', '.jpeg'   then 'image/jpeg'
+      when '.gif'            then 'image/gif'
+      when '.webp'           then 'image/webp'
+      when '.bmp'            then 'image/bmp'
+      when '.pdf'            then 'application/pdf'
+      when '.txt'            then 'text/plain'
+      when '.json'           then 'application/json'
+      when '.zip'            then 'application/zip'
+      when '.doc'            then 'application/msword'
+      when '.docx'           then 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+      when '.xls'            then 'application/vnd.ms-excel'
+      when '.xlsx'           then 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+      else                        'application/octet-stream'
+      end
+    end
+  end
+end

data/lib/ice_jade/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IceJade
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/ice_jade.rb

@@ -10,4 +10,5 @@ require_relative 'ice_jade/client_base'
 require_relative 'ice_jade/quantum/client'
 require_relative 'ice_jade/quantum/message'
 require_relative 'ice_jade/poster'
+require_relative 'ice_jade/getter'
 require_relative 'ice_jade/cradle'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ice-jade
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Frampt
@@ -9,8 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A lightweight Ruby SDK featuring Quantum (IM robot messaging) and Poster
-  (zero-dependency HTTP POST client with JSON/Form/Multipart support).
+description: A lightweight Ruby SDK featuring Quantum (IM robot messaging), Getter
+  & Poster (zero-dependency HTTP GET & POST clients with JSON/Form/Multipart support
+  and sharing a common IceJade::Transport layer).
 email:
 - 18995691365@189.cn
 executables:
@@ -24,10 +25,13 @@ files:
 - bin/cradle
 - bin/cradle-instance
 - config/cradle/poster_test.yml
+- examples/comparison_getter.rb
 - examples/comparison_poster.rb
 - examples/cradle_usage.rb
+- examples/getter_usage.rb
 - examples/poster_usage.rb
 - examples/quantum_usage.rb
+- lib/http_getter.rb
 - lib/http_poster.rb
 - lib/ice_jade.rb
 - lib/ice_jade/client_base.rb
@@ -35,11 +39,14 @@ files:
 - lib/ice_jade/cradle/server.rb
 - lib/ice_jade/cradle/yaml_server.rb
 - lib/ice_jade/error.rb
+- lib/ice_jade/getter.rb
+- lib/ice_jade/getter/client.rb
 - lib/ice_jade/poster.rb
 - lib/ice_jade/poster/client.rb
 - lib/ice_jade/quantum/client.rb
 - lib/ice_jade/quantum/message.rb
 - lib/ice_jade/response.rb
+- lib/ice_jade/transport.rb
 - lib/ice_jade/version.rb
 homepage: https://www.srdcloud.cn/codehub/Frampt/ice-jade
 licenses:
@@ -61,5 +68,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: IM webhook SDK & general-purpose HTTP POST client
+summary: IM webhook SDK & general-purpose HTTP POST/GET client
 test_files: []