ice-jade 0.6.0 → 0.8.0

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'