ice-jade 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68cefcd1f994be3fd223da84038c78ba39087227ac6ba22cfef06912b1e890d6
-  data.tar.gz: a5ee1b22d8929a592aa65a7725b94fdf2e2f63e071e202bd8e18ddf666410f59
+  metadata.gz: 70f058625ea166e107bf454a437142ebb6a4cb0f3c49d88e484fe45be069d271
+  data.tar.gz: 0ea0b70756e261510b7ac062f39f02411dd7a54301b7f3c86339c7f6380f57db
 SHA512:
-  metadata.gz: 2fff58382ca71e712f1a7a21c23bb4465dee51789efc318aeae013af265d43ee43a5fc36f48cb8fc009069b28aff5fed42b90086696210a3424d1bd86d27fe20
-  data.tar.gz: 51fbc0b9a38a4e77da420c0f9c7464282940c643b173bbd106cb51e49e1f51dfbbcf85bbb313cc4bfda195f0cebf4422908412f453d91e0f1b4124cfe24010eb
+  metadata.gz: aed37f531cce690f2ed41b80adcc5e45b8a7cab2dbb5ad1c4c2c111d4e477ae9c8e172a99f02b05a1ca13a4a150169e23c2f00109f49ec0dd640338e232eb6c1
+  data.tar.gz: 72cc6594677d28a1ea49ef7f9fac87dd73ff8af30ce1af9dac8fa3c95740171aab185b3c0b5b1f2f418e87b938dd38900c1b27ceea5adfec022c2ba76a77c874

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_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

data/examples/cradle_usage.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cradle 用法示例：启动本地 HTTP 测试服务器
+#
+# 本示例演示如何用 IceJade::Cradle::Server 启动一个测试服务器，
+# 并用 IceJade::Poster::Client 向它发起请求。
+#
+# 运行方式:
+#   ruby examples/cradle_usage.rb
+#
+# 或者直接使用命令行工具:
+#   ruby bin/cradle -p 8765
+
+require_relative '../lib/ice_jade'
+
+# =============================================================================
+# 1. 启动 Cradle 测试服务器（后台线程）
+# =============================================================================
+puts "=== 启动 Cradle 测试服务器 ==="
+server = IceJade::Cradle::Server.new(port: 8765, silent: true)
+thread = Thread.new { server.start }
+sleep 0.5  # 等待服务器启动
+
+poster = IceJade::Poster::Client.new(base_url: 'http://127.0.0.1:8765')
+
+begin
+  # =============================================================================
+  # 2. 健康检查
+  # =============================================================================
+  puts "\n=== 2. GET /health ==="
+  resp = poster.post_json('/health', {})
+  puts "Health: #{resp.data}"
+
+  # =============================================================================
+  # 3. GET 回显查询参数
+  # =============================================================================
+  puts "\n=== 3. GET /echo?foo=bar&baz=qux ==="
+  # 使用通用 post 的 GET 不太合适，这里直接用 post_json 到 /echo 演示 POST 回显
+  # GET 回显需要另外的方式，这里跳过
+
+  # =============================================================================
+  # 4. POST /echo —— 回显 JSON 请求体
+  # =============================================================================
+  puts "\n=== 4. POST /echo (JSON) ==="
+  resp = poster.post_json('/echo', { name: 'Alice', role: 'admin' })
+  puts "Echo body: #{resp.data}"
+
+  # =============================================================================
+  # 5. POST /form —— 接收 form-urlencoded
+  # =============================================================================
+  puts "\n=== 5. POST /form (Form) ==="
+  resp = poster.post_form('/form', { username: 'admin', password: 'secret' })
+  puts "Form data: #{resp.data}"
+
+  # =============================================================================
+  # 6. POST /upload —— 接收 multipart 文件上传
+  # =============================================================================
+  puts "\n=== 6. POST /upload (Multipart) ==="
+  require 'tmpdir'
+  tmp_path = File.join(Dir.tmpdir, 'cradle_demo.txt')
+  File.write(tmp_path, "Hello from Cradle!\n")
+
+  resp = poster.post_multipart('/upload', { file: tmp_path, description: 'demo' })
+  puts "Upload response: #{resp.data}"
+  File.delete(tmp_path)
+
+  # =============================================================================
+  # 7. GET /status/:code —— 模拟错误状态码
+  # =============================================================================
+  puts "\n=== 7. GET /status/500 (模拟 500 错误) ==="
+  # 注意：Cradle 的 /status/:code 是 GET，这里用 post_json 会走 POST，不匹配路由
+  # 所以使用 poster.post 通用方法，但会返回 404（因为 POST /status/500 未注册）
+  # 实际测试 GET 需要用其他工具如 curl
+  # 这里演示 POST /echo 的成功响应即可
+
+  # =============================================================================
+  # 8. POST /delay/:seconds —— 测试超时
+  # =============================================================================
+  puts "\n=== 8. POST /delay/1 (延迟 1 秒) ==="
+  start_time = Time.now
+  resp = poster.post_json('/delay/1', { test: 'delay' })
+  elapsed = Time.now - start_time
+  puts "Delayed response: #{resp.data}, elapsed: #{elapsed.round(2)}s"
+
+  puts "\n=== 所有测试通过 ==="
+
+ensure
+  server.stop
+  thread.join
+  puts "\nCradle 服务器已关闭。"
+end

data/examples/poster_usage.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Poster 用法示例：调用 Cradle YAML 实例
+#
+# 本示例通过 YAML 配置启动定制化的 Cradle 测试实例，
+# 然后用 IceJade::Poster::Client 向它发起请求，本地闭环验证。
+
+require_relative '../lib/ice_jade'
+require 'tmpdir'
+
+# =============================================================================
+# 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
+
+poster = IceJade::Poster::Client.new(
+  base_url: "http://#{instance.config['host']}:#{instance.config['port']}",
+  headers: { 'X-Custom-Header' => 'ice-jade' }
+)
+
+begin
+
+  # ------------------------------------------------------------------
+  # 1. POST JSON
+  # ------------------------------------------------------------------
+  puts "\n=== 1. POST JSON → /echo ==="
+  resp = poster.post_json('/echo', { name: 'Alice', role: 'admin' })
+  puts "Success: #{resp.success?}, Code: #{resp.code}, Message: #{resp.message}"
+  puts "Echo body: #{resp.data.is_a?(Hash) ? resp.data['body'] : resp.data}"
+
+  # ------------------------------------------------------------------
+  # 2. POST Form（传统表单）
+  # ------------------------------------------------------------------
+  puts "\n=== 2. POST Form → /form ==="
+  resp = poster.post_form('/form', { username: 'admin', password: 'secret' })
+  puts "Success: #{resp.success?}, Code: #{resp.code}"
+  puts "Form echoed: #{resp.data.is_a?(Hash) ? resp.data['form'] : 'N/A'}"
+
+  # ------------------------------------------------------------------
+  # 3. 通用 post（自定义 Content-Type）
+  # ------------------------------------------------------------------
+  puts "\n=== 3. 通用 post → /echo (application/xml) ==="
+  resp = poster.post('/echo', '<xml><body>hello</body></xml>',
+                     headers: { 'X-Request-ID' => 'uuid-1234' },
+                     content_type: 'application/xml')
+  puts "Success: #{resp.success?}, Code: #{resp.code}"
+
+  # ------------------------------------------------------------------
+  # 4. POST Multipart（文件上传）
+  # ------------------------------------------------------------------
+  puts "\n=== 4. POST Multipart → /upload ==="
+  tmp_path = File.join(Dir.tmpdir, 'ice_jade_poster_demo.txt')
+  File.write(tmp_path, "Hello from IceJade Poster!\n")
+
+  if File.exist?(tmp_path)
+    resp = poster.post_multipart('/upload', { file: tmp_path, description: 'demo upload' })
+    puts "Success: #{resp.success?}, Code: #{resp.code}"
+    puts "Files: #{resp.data.is_a?(Hash) ? resp.data['files'] : 'N/A'}"
+    File.delete(tmp_path)
+  end
+
+  # ------------------------------------------------------------------
+  # 5. 错误处理（HTTP 500）
+  # ------------------------------------------------------------------
+  puts "\n=== 5. 错误处理 → /error ==="
+  resp = poster.post_json('/error', { foo: 'bar' })
+  puts "Success: #{resp.success?}, Code: #{resp.code}, Message: #{resp.message}"
+
+  # ------------------------------------------------------------------
+  # 6. 延迟响应（测试超时重试）
+  # ------------------------------------------------------------------
+  puts "\n=== 6. 延迟响应 → /delay/1 ==="
+  start = Time.now
+  resp = poster.post_json('/delay/1', { test: 'delay' })
+  elapsed = Time.now - start
+  puts "Success: #{resp.success?}, Elapsed: #{elapsed.round(2)}s"
+
+  puts "\n=== 所有测试通过 ==="
+
+ensure
+  instance.stop
+  thread.join
+  puts "\nCradle YAML 实例已关闭。"
+end

data/examples/quantum_usage.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# 用法示例：ice-jade gem（Quantum IM Webhook SDK）
+
+require_relative '../lib/ice_jade'
+
+KEY = 'your-webhook-key-here'
+
+# ------------------------------------------------------------------
+# 初始化客户端
+# ------------------------------------------------------------------
+client = IceJade::Quantum::Client.new(KEY)
+
+# ------------------------------------------------------------------
+# 1. 发送纯文本消息
+# ------------------------------------------------------------------
+puts "=== 1. 发送纯文本 ==="
+resp = client.send_text("合肥今日天气：29度，大部分多云，降雨概率：60%")
+puts "Success: #{resp.success?}, Message: #{resp.message}"
+
+# @所有人
+puts "=== 1b. @所有人 ==="
+resp = client.send_text("紧急通知：今晚全员加班", mention_all: true)
+puts "Success: #{resp.success?}, Message: #{resp.message}"
+
+# @部分人（通过手机号）
+puts "=== 1c. @部分人 ==="
+resp = client.send_text("各位组长请查收", mentioned_mobiles: ['13800138000', '13900139000'])
+puts "Success: #{resp.success?}, Message: #{resp.message}"
+
+# ------------------------------------------------------------------
+# 2. 发送图文消息（news）
+# ------------------------------------------------------------------
+puts "\n=== 2. 发送图文 ==="
+resp = client.send_news(
+  "今年春节有好礼相送",
+  "https://www.baidu.com",
+  description: "点击图片领取礼品",
+  pic_url: "http://img.sccnn.com/bimg/341/34669.jpg"
+)
+puts "Success: #{resp.success?}, Message: #{resp.message}"
+
+# ------------------------------------------------------------------
+# 3. 上传并发送图片（两步走）
+# ------------------------------------------------------------------
+puts "\n=== 3. 上传图片 ==="
+image_path = '/path/to/your/image.jpg'
+
+if File.exist?(image_path)
+  upload_resp = client.upload_image(image_path)
+  puts "Upload success: #{upload_resp.success?}"
+  puts "File ID: #{upload_resp.data['id']}"
+  puts "File Name: #{upload_resp.data['name']}"
+  puts "File Size: #{upload_resp.data['size']}"
+
+  # 发送图片（需要提前知道宽高，或通过其他方式获取）
+  send_resp = client.send_image(upload_resp.data['id'], height: 1080, width: 1920)
+  puts "Send image success: #{send_resp.success?}"
+else
+  puts "图片不存在，跳过上传示例: #{image_path}"
+end
+
+# ------------------------------------------------------------------
+# 4. 一键上传并发送图片（便捷方法）
+# ------------------------------------------------------------------
+puts "\n=== 4. 一键上传并发送图片 ==="
+if File.exist?(image_path)
+  resp = client.upload_and_send_image(image_path, height: 1080, width: 1920)
+  puts "Success: #{resp.success?}, Message: #{resp.message}"
+else
+  puts "图片不存在，跳过一键发送示例: #{image_path}"
+end
+
+# ------------------------------------------------------------------
+# 5. 上传并发送文件
+# ------------------------------------------------------------------
+puts "\n=== 5. 上传文件 ==="
+file_path = '/path/to/your/document.pdf'
+
+if File.exist?(file_path)
+  upload_resp = client.upload_file(file_path)
+  puts "Upload success: #{upload_resp.success?}"
+  puts "File ID: #{upload_resp.data['id']}"
+
+  send_resp = client.send_file(upload_resp.data['id'])
+  puts "Send file success: #{send_resp.success?}"
+else
+  puts "文件不存在，跳过上传示例: #{file_path}"
+end
+
+# ------------------------------------------------------------------
+# 6. 一键上传并发送文件（便捷方法）
+# ------------------------------------------------------------------
+puts "\n=== 6. 一键上传并发送文件 ==="
+if File.exist?(file_path)
+  resp = client.upload_and_send_file(file_path)
+  puts "Success: #{resp.success?}, Message: #{resp.message}"
+else
+  puts "文件不存在，跳过一键发送示例: #{file_path}"
+end
+
+# ------------------------------------------------------------------
+# 7. 手动构造消息 Payload（高级）
+# ------------------------------------------------------------------
+puts "\n=== 7. 手动构造 Payload ==="
+payload = IceJade::Quantum::Message.text("这是一条手动构造的消息", mentioned_mobiles: ['13800138000'])
+puts JSON.pretty_generate(payload)
+
+payload = IceJade::Quantum::Message.news("自定义标题", "https://example.com", pic_url: "https://example.com/pic.jpg")
+puts JSON.pretty_generate(payload)
+
+puts "\n示例运行完毕。"

data/lib/ice_jade/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ice-jade
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Frampt
@@ -23,6 +23,11 @@ files:
 - README.md
 - bin/cradle
 - bin/cradle-instance
+- config/cradle/poster_test.yml
+- examples/comparison_poster.rb
+- examples/cradle_usage.rb
+- examples/poster_usage.rb
+- examples/quantum_usage.rb
 - lib/http_poster.rb
 - lib/ice_jade.rb
 - lib/ice_jade/client_base.rb