Class: IceJade::Poster::Client

Inherits:
Object
  • Object
show all
Includes:
Transport
Defined in:
lib/ice_jade/poster/client.rb

Overview

通用 HTTP POST 客户端

零外部依赖，支持 JSON / Form / Multipart 三种常用提交方式， 内置超时控制、指数退避重试、统一 Response 包装，与 Quantum 模块风格一致。 底层传输能力（URI 拼接、请求执行、响应适配、超时重试）复用 IceJade::Transport，

Examples:

基础用法

poster = IceJade::Poster::Client.new(
  base_url: 'https://api.example.com',
  headers:  { 'Authorization' => 'Bearer token' },
  timeout:  30
)
resp = poster.post_json('/users', { name: 'Alice' })
puts resp.data if resp.success?

Constant Summary

Constants included from Transport

Transport::HTTP_STATUS_TEXT

Instance Attribute Summary

Attributes included from Transport

#base_url, #default_headers, #max_retries, #open_timeout, #timeout

Instance Method Summary collapse

Methods included from Transport

#adapt_response, #apply_headers, #build_multipart, #build_uri, #execute, #init_transport, #merge_headers, #mime_type, #normalize_headers

Constructor Details

#initialize(base_url: nil, headers: {}, timeout: 60, open_timeout: 10, max_retries: 2) ⇒ Client

Returns a new instance of Client.

Parameters:

  • base_url (String, nil) (defaults to: nil) —

    基础 URL，后续请求可传相对路径

  • headers (Hash) (defaults to: {}) —

    默认请求头（每次请求自动合并，同名会被覆盖）

  • timeout (Integer) (defaults to: 60) —

    读取超时（秒），默认 60

  • open_timeout (Integer) (defaults to: 10) —

    连接超时（秒），默认 10

  • max_retries (Integer) (defaults to: 2) —

    超时后最大重试次数，默认 2



30
31
32
33
34
 
# File 'lib/ice_jade/poster/client.rb', line 30

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

Instance Method Details

#post(url, body = nil, headers: {}, content_type: 'application/json') ⇒ IceJade::Response

发送通用 POST 请求

Parameters:

  • url (String) —

    完整 URL 或相对路径（需先设置 base_url）

  • body (String, Hash, nil) (defaults to: nil) —

    请求体；Hash 会根据 content_type 自动序列化

  • headers (Hash) (defaults to: {}) —

    额外请求头（与默认头合并，同名覆盖）

  • content_type (String) (defaults to: 'application/json') —

    Content-Type，默认 application/json

Returns:



47
48
49
50
51
52
 
# File 'lib/ice_jade/poster/client.rb', line 47

def post(url, body = nil, headers: {}, content_type: 'application/json')
  uri = build_uri(url)
  merged_headers = merge_headers(default_headers, normalize_headers(headers))
  req = build_request(uri, body, content_type, merged_headers)
  execute(uri, req)
end

#post_form(url, params = {}, headers = {}) ⇒ IceJade::Response

POST Form（传统表单提交）

Parameters:

  • url (String)
  • params (Hash) (defaults to: {}) —

    请求参数，自动转为 URL-encoded

  • headers (Hash) (defaults to: {}) —

    额外请求头

Returns:



72
73
74
 
# File 'lib/ice_jade/poster/client.rb', line 72

def post_form(url, params = {}, headers = {})
  post(url, params, headers: headers, content_type: 'application/x-www-form-urlencoded')
end

#post_json(url, params = {}, headers = {}) ⇒ IceJade::Response

POST JSON（API 调用最常用）

Parameters:

  • url (String)
  • params (Hash) (defaults to: {}) —

    请求参数，自动转为 JSON

  • headers (Hash) (defaults to: {}) —

    额外请求头

Returns:



63
64
65
 
# File 'lib/ice_jade/poster/client.rb', line 63

def post_json(url, params = {}, headers = {})
  post(url, params, headers: headers, content_type: 'application/json')
end

#post_multipart(url, params = {}, headers = {}) ⇒ IceJade::Response

POST Multipart（文件上传）

Parameters:

  • url (String)
  • params (Hash) (defaults to: {}) —

    支持文件字段（值为本地文件路径字符串） 示例: { file: '/path/to/file.png', purpose: 'image' }

  • headers (Hash) (defaults to: {}) —

    额外请求头

Returns:



83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/ice_jade/poster/client.rb', line 83

def post_multipart(url, params = {}, headers = {})
  uri = build_uri(url)
  body, boundary = build_multipart(params)
  merged_headers = merge_headers(default_headers, normalize_headers(headers))
  merged_headers['Content-Type'] = "multipart/form-data; boundary=#{boundary}"

  req = Net::HTTP::Post.new(uri)
  apply_headers(req, merged_headers)
  req.body = body

  execute(uri, req)
end