Class: IceJade::Poster::Client

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

Overview

通用 HTTP POST 客户端

零外部依赖，支持 JSON / Form / Multipart 三种常用提交方式， 内置超时控制、指数退避重试、统一 Response 包装，与 Quantum 模块风格一致。

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?

Instance Attribute Summary collapse

Instance Method Summary collapse

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



34
35
36
37
38
39
40
 
# File 'lib/ice_jade/poster/client.rb', line 34

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
end

Instance Attribute Details

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



27
28
29
 
# File 'lib/ice_jade/poster/client.rb', line 27

def base_url
  @base_url
end

#default_headers ⇒ Object (readonly)

Returns the value of attribute default_headers.



27
28
29
 
# File 'lib/ice_jade/poster/client.rb', line 27

def default_headers
  @default_headers
end

#max_retries ⇒ Object (readonly)

Returns the value of attribute max_retries.



27
28
29
 
# File 'lib/ice_jade/poster/client.rb', line 27

def max_retries
  @max_retries
end

#open_timeout ⇒ Object (readonly)

Returns the value of attribute open_timeout.



27
28
29
 
# File 'lib/ice_jade/poster/client.rb', line 27

def open_timeout
  @open_timeout
end

#timeout ⇒ Object (readonly)

Returns the value of attribute timeout.



27
28
29
 
# File 'lib/ice_jade/poster/client.rb', line 27

def timeout
  @timeout
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:



53
54
55
56
57
58
 
# File 'lib/ice_jade/poster/client.rb', line 53

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:



78
79
80
 
# File 'lib/ice_jade/poster/client.rb', line 78

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:



69
70
71
 
# File 'lib/ice_jade/poster/client.rb', line 69

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:



89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/ice_jade/poster/client.rb', line 89

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