k3cloud-sdk 0.4.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 148509b4c220bf006114ffc6d60dec5b540abe2e33761dad837ef395e3553923
-  data.tar.gz: 93a6ae34b81c0998a1b02cc9405404ddae16eb4238497bf042cbd00fe53e5726
+  metadata.gz: 5dfedb0c66eddf2de607406e2cf083b98f54350412d9cbb2699d177eb66c347a
+  data.tar.gz: b73a7c6847c615b4d2ec9fcb0dbacce4e69078ba24e204fa2cf850974a28404c
 SHA512:
-  metadata.gz: b2c060e153416fd6bb8fcf9d3b3c06127a4beb9fde7a66d276742d60b422d929d2aa6d1f7dbfdf8cd8cc17175f1c48197f3c022707fed89bd73601829713f931
-  data.tar.gz: 9505afcb1b6ff35e631abec3d9f97db35c8add981c6046ddfbac17560c9aaea5ffd29b6c62d548fd0e51e98e039f0c82a141f15e96e2d7e24a8b14cc6a2fe3d6
+  metadata.gz: 14bba40c28f9a4909551df05847b713ffce4029928fc5b9a82b020c95d7f1f155fff0a2eccce316b54c261c3bdcc3e085e823702eb3a8bf11787e181c0f52a6e
+  data.tar.gz: 1339bf2093aad7ee854a1d342d50341f0f0bcaf376daf68e620914271d3576fbcbdfc7ee41f08d8925192a150038809298c06614646042a205a68306ed9971b1

data/.rubocop.yml

@@ -1,5 +1,13 @@
 AllCops:
-  TargetRubyVersion: 2.0
+  TargetRubyVersion: 2.5
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "**/*.md"
+    - "ChangeLog*"
+    - "CHANGELOG*"
+    - "vendor/**/*"
+    - "pkg/**/*"
 
 Style/StringLiterals:
   Enabled: true
@@ -11,3 +19,37 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+# 本仓库既有签名/加密逻辑偏过程式，文档与度量类 cops 放宽以避免大改业务逻辑。
+Style/Documentation:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/FormatString:
+  EnforcedStyle: format
+
+Naming/FileName:
+  Exclude:
+    - "lib/k3cloud-sdk.rb"
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "k3cloud.gemspec"
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/ParameterLists:
+  Max: 8

data/CHANGELOG.md

@@ -1,5 +1,101 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-17
+
+### ⚠ Breaking Changes
+
+- 最低 Ruby 版本提升至 `>= 2.5.0`。
+- 默认启用 HTTPS 证书校验；私有云自签证书需显式设置 `Configuration#verify_ssl = false`。
+- `Configuration` 为 `lcid`、`connect_timeout`(30s)、`request_timeout`(60s)、`verify_ssl` 提供默认值。
+- 工具类与常量迁移至 `K3cloud` 命名空间（`K3cloud::Base64Utils`、`K3cloud::MD5Utils`、`K3cloud::ConstDefine`），不再保留无命名空间别名。
+- `Http` 构造参数改为关键字参数。
+
+### Security
+
+- 构造签名头失败时不再静默返回空 header，改为抛出异常。
+- 签名密钥为空时 `MD5Utils.hash_mac` 改为抛出 `ArgumentError`。
+
+### Fixed
+
+- 修复 `MD5Utils.encrypt` 在 Ruby 下始终返回空字符串的 bug。
+- 修复公有云请求 URL 出现双斜杠的问题。
+
+### Added
+
+- 日志输出支持可配置格式：`Configuration#log_format` 取 `:text`（默认，常规 Logger 格式）或 `:json`（每行一个 JSON，便于采集与检索）。
+- 支持注入自定义 logger（`K3cloud.logger = Rails.logger`）与重建默认 logger（`K3cloud.reset_logger!`）。
+
+## [0.4.7] - 2025-02-18
+
+### Fixed
+
+- 修复 `execute_bill_query` 查询成功时误返回空数组、丢失业务数据的问题。
+
+## [0.4.6] - 2025-02-18
+
+### Fixed
+
+- 修复 `execute_bill_query` 在空结果时误判为错误的问题。
+
+## [0.4.5] - 2025-02-18
+
+### Changed
+
+- 自定义错误类型统一改为抛出 `K3cloud::ResponseError`。
+- `execute_bill_query` 增加对错误返回结构的识别：当首行首列为 Hash 时记录日志并返回空数组。
+- User-Agent 携带 SDK 版本与运行环境信息。
+
+## [0.4.4] - 2024-07-19
+
+### Added
+
+- HTTP 请求超时自动重试（最多 5 次，间隔 5 秒）。
+
+## [0.4.3] - 2023-11-29
+
+### Added
+
+- 新增统一异常类 `K3cloud::ResponseError`、`K3cloud::K3cloudError`。
+
+## [0.4.2] - 2023-11-29
+
+### Fixed
+
+- 修复非 200/206 响应被误判为失败的问题（`response.code` 为字符串比较恒为假）。
+
+## [0.4.1] - 2023-11-28
+
+### Changed
+
+- HTTP 请求失败时改为抛出异常，不再静默返回 `nil`。
+
+## [0.4.0] - 2023-11-17
+
+### Changed
+
+- 兼容更低版本 Ruby 语法。
+
+## [0.3.0] - 2023-11-14
+
+### Added
+
+- 多账号配置支持：通过 `K3cloud.new_api(config)` 创建多账号客户端实例。
+
+## [0.2.0] - 2023-10-09
+
+### Fixed
+
+- 修复入口文件大小写问题导致部分平台上 `require "k3cloud-sdk"` 失败。
+
 ## [0.1.0] - 2023-09-26
 
-- Initial release
+### Added
+
+- 初始版本：封装金蝶云星空 OpenApi，涵盖暂存/保存/提交/审核/查看/查询/删除/下推/分配等单据操作及附件、工作流、报表等共 26 个业务方法。

data/Gemfile

@@ -6,5 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
-
 gem "rspec", "~> 3.0"
+gem "rubocop", require: false
+gem "webmock", "~> 3.0", group: :test
+# Ruby 3.x: base64 became a bundled gem, declare explicitly so vendored bundle resolves it.
+gem "base64", require: false
+gem "json", require: false

data/Gemfile.lock

@@ -1,13 +1,35 @@
 PATH
   remote: .
   specs:
-    k3cloud-sdk (0.4.6)
+    k3cloud-sdk (0.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
     diff-lcs (1.5.0)
+    hashdiff (1.2.1)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
     rake (13.0.6)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -21,15 +43,42 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.1)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-25
 
 DEPENDENCIES
+  base64
+  json
   k3cloud-sdk!
   rake (~> 13.0)
   rspec (~> 3.0)
+  rubocop
+  webmock (~> 3.0)
 
 BUNDLED WITH
    2.4.14

data/README.md

@@ -1,4 +1,5 @@
 # K3cloud-sdk
+
 Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology to avoid plaintext transmission of keys and enables automatic login.
 
 ## Installation
@@ -14,6 +15,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 ## Usage
 
 #### 1. Single Account Configuration:
+
 You'll need to configure it in `config/initializers/k3cloud.rb`:
 
 ```ruby
@@ -27,6 +29,7 @@ You'll need to configure it in `config/initializers/k3cloud.rb`:
 ```
 
 Then you can call the k3cloud API using the following code:
+
 ```ruby
   data = {
     FormId: "",
@@ -37,6 +40,7 @@ Then you can call the k3cloud API using the following code:
 ```
 
 #### 2. Multi Account Configuration:
+
 You'll need to configure it in `config/initializers/k3cloud.rb`:
 
 ```ruby
@@ -56,19 +60,20 @@ You'll need to configure it in `config/initializers/k3cloud.rb`:
     c.server_url = ENV['K3CLOUD2_SERVER_URL']
   end
 
-    K3cloud1 = K3cloud.new_api(config1)
-    K3cloud2 = K3cloud.new_api(config2)
+  client1 = K3cloud.new_api(config1)
+  client2 = K3cloud.new_api(config2)
 ```
 
 Then you can call the k3cloud API using the following code:
+
 ```ruby
   data = {
     FormId: "",
     FieldKeys: "",
     FilterString: ""
   }
-  K3cloud1.execute_bill_query(data)
-  K3cloud2.execute_bill_query(data)
+  client1.execute_bill_query(data)
+  client2.execute_bill_query(data)
 ```
 
 ## Development
@@ -79,7 +84,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zevinto/k3cloud-sdk. 
+Bug reports and pull requests are welcome on GitHub at https://github.com/zevinto/k3cloud-sdk.
 This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zevinto/k3cloud-sdk/blob/main/CODE_OF_CONDUCT.md).
 
 ## License

data/k3cloud.gemspec

@@ -9,11 +9,15 @@ Gem::Specification.new do |spec|
   spec.email = ["zevinto@163.com"]
 
   spec.summary = "Ruby Gem for K3cloud API."
-  spec.description = "Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology to avoid plaintext transmission of keys and enables automatic login."
+  spec.description = "Ruby Gem for K3cloud OpenApi. Uses cryptographic signature technology to avoid " \
+                     "plaintext transmission of keys and enables automatic login."
   spec.homepage = "https://github.com/zevinto/k3cloud-sdk"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.0.0"
+  spec.required_ruby_version = ">= 2.5.0"
   spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/lib/k3cloud/configuration.rb

@@ -29,7 +29,16 @@ module K3cloud
     # 组织编码，启用多组织时配置对应的组织编码才有效
     attr_accessor :org_num
 
-    attr_accessor :connect_timeout, :request_timeout
+    # 连接/请求超时（秒）。私有云自签证书时可设 verify_ssl=false 跳过校验
+    attr_accessor :connect_timeout, :request_timeout, :verify_ssl
+
+    # 日志输出格式：:text（默认，常规 Logger 格式）或 :json（每行一个 JSON）
+    attr_accessor :log_format
+
+    DEFAULT_LCID = 2052
+    DEFAULT_CONNECT_TIMEOUT = 30
+    DEFAULT_REQUEST_TIMEOUT = 60
+    DEFAULT_LOG_FORMAT = :text
 
     def initialize(options = {})
       @acct_id          = options[:acct_id]
@@ -39,14 +48,24 @@ module K3cloud
       @app_secret       = options[:app_secret]
       @server_url       = options[:server_url]
       @org_num          = options[:org_num]
-      @connect_timeout  = options[:connect_timeout]
-      @request_timeout  = options[:request_timeout]
+      @lcid             = options.fetch(:lcid, DEFAULT_LCID)
+      @connect_timeout  = options.fetch(:connect_timeout, DEFAULT_CONNECT_TIMEOUT)
+      @request_timeout  = options.fetch(:request_timeout, DEFAULT_REQUEST_TIMEOUT)
+      @verify_ssl       = options.fetch(:verify_ssl, true)
+      @log_format       = options.fetch(:log_format, DEFAULT_LOG_FORMAT)
 
       yield(self) if block_given?
     end
 
-    def self.default
-      @@default ||= Configuration.new
+    class << self
+      def default
+        @default ||= Configuration.new
+      end
+
+      # 测试或重新配置时重置默认配置
+      def reset_default!
+        @default = nil
+      end
     end
   end
 end

data/lib/k3cloud/errors/k3cloud_error.rb

@@ -14,17 +14,22 @@ module K3cloud
     end
 
     def self.parse(json)
+      return nil if json.nil? || json.to_s.empty?
+
+      json = json.to_s
       index = json.index("{")
-      json = json[index..-1] if index >= 0
+      json = json[index..-1] if index
 
       parsed_json = JSON.parse(json)
       kd_error = K3cloudError.new
       kd_error.message = parsed_json["Message"]
-      kd_error.inner_ex_wrapper = K3cloudError.parse(parsed_json["InnerExWrapper"].to_json)
-      kd_error.inner_exception = K3cloudError.parse(parsed_json["InnerException"].to_json)
+      inner_wrapper = parsed_json["InnerExWrapper"]
+      inner_exception = parsed_json["InnerException"]
+      kd_error.inner_ex_wrapper = inner_wrapper ? K3cloudError.parse(inner_wrapper.to_json) : nil
+      kd_error.inner_exception = inner_exception ? K3cloudError.parse(inner_exception.to_json) : nil
       kd_error
     rescue StandardError => e
-      K3cloud.logger.error({ errmsg: "Failed to parse exception message. #{e.message}", backtrace: "#{e.backtrace}", type: 'error', lever: 'ERROR' })
+      K3cloud.logger.error({ msg: "Failed to parse exception message. #{e.message}", type: "error", level: "ERROR" })
       nil
     end
   end

data/lib/k3cloud/http.rb

@@ -9,27 +9,22 @@ require "json"
 module K3cloud
   # HTTP Client
   class Http
-    attr_accessor :url, :header, :body, :connect_timeout, :request_timeout, :status_code
+    attr_accessor :url, :header, :body, :connect_timeout, :request_timeout, :verify_ssl, :status_code
 
-    def initialize(url, header, body, connect_timeout = 120, request_timeout = 120)
+    def initialize(url:, header:, body:, connect_timeout: Configuration::DEFAULT_CONNECT_TIMEOUT,
+                   request_timeout: Configuration::DEFAULT_REQUEST_TIMEOUT, verify_ssl: true)
       @url = url
       @header = header || {}
       @body = body
       @connect_timeout = connect_timeout
       @request_timeout = request_timeout
+      @verify_ssl = verify_ssl
     end
 
     def post
       uri = URI.parse(@url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      # SSL/TLS configuration
-      if uri.scheme == "https"
-        http.use_ssl = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-      end
+      http = build_http(uri)
 
-      http.open_timeout = @connect_timeout
-      http.read_timeout = @request_timeout
       request = Net::HTTP::Post.new(uri.request_uri)
       request.initialize_http_header(@header)
       request["Content-Type"] = "application/json"
@@ -43,14 +38,36 @@ module K3cloud
       response.body
     rescue Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout => e
       raise K3cloud::ResponseError, "Request timed out: #{e.message}"
+    rescue K3cloud::ResponseError
+      raise
     rescue Net::HTTPServerError => e
       raise K3cloud::ResponseError, "Server error: #{e.message}"
-    rescue => e
+    rescue StandardError => e
       raise K3cloud::ResponseError, "Unexpected error: #{e.message}"
     end
 
     private
 
+    def build_http(uri)
+      http = connection(uri) || Net::HTTP.new(uri.host, uri.port)
+      configure_ssl!(http, uri) if uri.scheme == "https"
+      http.open_timeout = @connect_timeout
+      http.read_timeout = @request_timeout
+      http.write_timeout = @request_timeout if http.respond_to?(:write_timeout=)
+      http.ssl_timeout = @request_timeout if http.respond_to?(:ssl_timeout=) && uri.scheme == "https"
+      http
+    end
+
+    def configure_ssl!(http, _uri)
+      http.use_ssl = true
+      http.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+    end
+
+    # 子类可覆盖以注入复用的连接（如 Net::HTTP::Persistent）。
+    def connection(_uri)
+      nil
+    end
+
     # Generate User-Agent string with client info
     def generate_user_agent
       "Kingdee/Ruby WebApi SDK(v#{K3cloud::VERSION}) (Ruby #{RUBY_VERSION}; #{RUBY_PLATFORM})"

data/lib/k3cloud/k3cloud_api.rb

@@ -135,12 +135,18 @@ module K3cloud
 
     private
 
+    # 金蝶 ExecuteBillQuery 在出错时会把错误信息放在首行首列（一个 Hash），
+    # 正常查询则返回二维数组。这里识别并记录错误，避免把错误对象当业务数据返回。
     def handle_query_result(rows)
-      if !rows[0].nil? && !rows[0].empty? && (result = rows[0][0]).is_a?(Hash)
-        K3cloud.logger.error({ errmsg: result, type: 'error', lever: 'ERROR' })
+      return rows if rows.nil? || rows.empty?
+
+      first_row = rows[0]
+      result = first_row.nil? || first_row.empty? ? nil : first_row[0]
+      if result.is_a?(Hash)
+        K3cloud.logger.error({ msg: result, type: "error", level: "ERROR" })
         []
       else
-        []
+        rows
       end
     end
   end

data/lib/k3cloud/utils/base64_utils.rb

@@ -2,18 +2,16 @@
 
 require "base64"
 
-module Base64Utils
-  def self.encoding_to_base64(buffer)
-    b64buffer = Base64.strict_encode64(buffer.pack("C*"))
-    b64buffer.force_encoding("UTF-8")
-  rescue StandardError => e
-    raise e
-  end
+module K3cloud
+  module Base64Utils
+    def self.encoding_to_base64(buffer)
+      b64buffer = Base64.strict_encode64(buffer.pack("C*"))
+      b64buffer.force_encoding("UTF-8")
+    end
 
-  def self.decoding_from_base64(base64)
-    buffer = base64.encode("UTF-8")
-    Base64.strict_decode64(buffer).bytes
-  rescue StandardError => e
-    raise e
+    def self.decoding_from_base64(base64)
+      buffer = base64.encode("UTF-8")
+      Base64.strict_decode64(buffer).bytes
+    end
   end
 end

data/lib/k3cloud/utils/const_define.rb

@@ -1,43 +1,45 @@
 # frozen_string_literal: true
 
-module ConstDefine
-  X_API_CLIENT_ID = "X-Api-ClientID"
+module K3cloud
+  module ConstDefine
+    X_API_CLIENT_ID = "X-Api-ClientID"
 
-  X_API_AUTH_VERSION = "X-Api-Auth-Version"
+    X_API_AUTH_VERSION = "X-Api-Auth-Version"
 
-  X_API_TIMESTAMP = "x-api-timestamp"
+    X_API_TIMESTAMP = "x-api-timestamp"
 
-  X_API_NONCE = "x-api-nonce"
+    X_API_NONCE = "x-api-nonce"
 
-  X_API_SIGN_HEADERS = "x-api-signheaders"
+    X_API_SIGN_HEADERS = "x-api-signheaders"
 
-  X_API_SIGNATURE = "X-Api-Signature"
+    X_API_SIGNATURE = "X-Api-Signature"
 
-  X_KD_APP_KEY = "X-Kd-Appkey"
+    X_KD_APP_KEY = "X-Kd-Appkey"
 
-  X_KD_APP_DATA = "X-Kd-Appdata"
+    X_KD_APP_DATA = "X-Kd-Appdata"
 
-  X_KD_SIGNATURE = "X-Kd-Signature"
+    X_KD_SIGNATURE = "X-Kd-Signature"
 
-  KD_SERVICE_SESSIONID = "kdservice-sessionid"
+    KD_SERVICE_SESSIONID = "kdservice-sessionid"
 
-  SESSION_ID = "ASP.NET_SessionId"
+    SESSION_ID = "ASP.NET_SessionId"
 
-  X_KD_SID = "SID"
+    X_KD_SID = "SID"
 
-  COOKIE_SET = "Set-Cookie"
+    COOKIE_SET = "Set-Cookie"
 
-  BEGIN_METHOD_HEADER = "beginmethod"
+    BEGIN_METHOD_HEADER = "beginmethod"
 
-  QUERY_METHOD_HEADER = "querymethod"
+    QUERY_METHOD_HEADER = "querymethod"
 
-  BEGIN_METHOD_METHOD = "BeginQueryImpl"
+    BEGIN_METHOD_METHOD = "BeginQueryImpl"
 
-  QUERY_METHOD_METHOD = "QueryAsyncResult"
+    QUERY_METHOD_METHOD = "QueryAsyncResult"
 
-  QUERY_INVODE_STATE_PENDING = 0
+    QUERY_INVODE_STATE_PENDING = 0
 
-  QUERY_INVODE_STATE_RUNNING = 1
+    QUERY_INVODE_STATE_RUNNING = 1
 
-  QUERY_INVODE_STATE_COMPLETE = 2
+    QUERY_INVODE_STATE_COMPLETE = 2
+  end
 end

data/lib/k3cloud/utils/md5_utils.rb

@@ -3,33 +3,26 @@
 require "digest"
 require "base64"
 
-module MD5Utils
-  def self.encrypt(data_str)
-    m = Digest::MD5.new
-    m.update(data_str.encode("UTF-8"))
-    s = m.digest
-    result = ""
+module K3cloud
+  module MD5Utils
+    UNSECURE_KEY = "0054f397c6234378b09ca7d3e5debce7"
 
-    s.each_byte do |byte|
-      result += (byte & 0xFF | -256).to_s(16)[6..-1]
+    # 返回 32 位小写十六进制 MD5。原来的逐字节位运算 hack 在 Ruby 下会得到 `nil`，
+    # 且被 rescue 吞掉返回空串，故直接使用 Digest::MD5.hexdigest。
+    def self.encrypt(data_str)
+      Digest::MD5.hexdigest(data_str.encode("UTF-8"))
     end
 
-    result
-  rescue StandardError => e
-    e.backtrace
-    ""
-  end
+    def self.hash_mac(data, secret)
+      raise ArgumentError, "secret is required for HMAC" if secret.nil? || secret.to_s.empty?
 
-  def self.hash_mac(data, secret)
-    kd_mac = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), secret, data)
-    hex_string = bytes_to_hex(kd_mac.bytes)
-    Base64.strict_encode64(hex_string)
-  rescue StandardError => e
-    e.backtrace
-    nil
-  end
+      kd_mac = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), secret, data)
+      hex_string = bytes_to_hex(kd_mac.bytes)
+      Base64.strict_encode64(hex_string)
+    end
 
-  def self.bytes_to_hex(bytes)
-    bytes.map { |byte| byte.to_s(16).rjust(2, "0") }.join
+    def self.bytes_to_hex(bytes)
+      bytes.map { |byte| byte.to_s(16).rjust(2, "0") }.join
+    end
   end
 end

data/lib/k3cloud/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K3cloud
-  VERSION = "0.4.6"
+  VERSION = "0.5.0"
 end

data/lib/k3cloud/web_api_client.rb

@@ -22,7 +22,8 @@ module K3cloud
         error = K3cloudError.parse(result)
         raise K3cloud::ResponseError, result if error.nil?
 
-        message = error.inner_ex_wrapper.nil? ? error.message : "#{error.message} --> #{error.inner_ex_wrapper&.message}"
+        inner_msg = error.inner_ex_wrapper&.message
+        message = inner_msg ? "#{error.message} --> #{inner_msg}" : error.message
         raise K3cloud::ResponseError, message
 
       else
@@ -42,28 +43,37 @@ module K3cloud
 
       header = build_header(url_path(url))
       body = { parameters: parameters }
-      request = Http.new(url, header, body, @config.connect_timeout, @config.request_timeout)
+      request = Http.new(
+        url: url,
+        header: header,
+        body: body,
+        connect_timeout: @config.connect_timeout,
+        request_timeout: @config.request_timeout,
+        verify_ssl: @config.verify_ssl
+      )
       request.post
     end
 
     def build_url(service_name)
-      base_url = if @config.server_url.nil? || @config.server_url.empty?
-              "https://api.kingdee.com/galaxyapi/"
-            else
-              @config.server_url.to_s.strip.chomp("/")
-            end
       "#{base_url}/#{service_name}.common.kdsvc"
     end
 
-    def url_path(url)
-      if url.start_with?("http")
-        index = url.index("/", 10)
-        index > -1 ? url[index..-1] : url
+    def base_url
+      server = @config.server_url
+      if server.nil? || server.empty?
+        "https://api.kingdee.com/galaxyapi"
       else
-        url
+        server.to_s.strip.chomp("/")
       end
     end
 
+    def url_path(url)
+      return url unless url.start_with?("http")
+
+      index = url.index("/", 10)
+      index ? url[index..-1] : url
+    end
+
     # @note: https://vip.kingdee.com/knowledge/specialDetail/229961573895771136?category=229964512944566016&id=423060878259269120&productLineId=1
     def build_header(url)
       header = {}
@@ -94,9 +104,6 @@ module K3cloud
         header[ConstDefine::X_KD_SIGNATURE] = kd_signature
       end
       header
-    rescue StandardError => e
-      K3cloud.logger.error({ errmsg: "Build header exception.", backtrace: "#{e.backtrace}", type: 'error', lever: 'ERROR' })
-      {}
     end
 
     def decode_sec(sec)

data/lib/k3cloud.rb

@@ -2,6 +2,7 @@
 
 require_relative "k3cloud/version"
 require "logger"
+require "json"
 require "k3cloud/configuration"
 require "k3cloud/k3cloud_api"
 require "forwardable"
@@ -19,20 +20,67 @@ module K3cloud
     end
 
     def logger
-      @logger ||= ::Logger.new($stderr)
+      @logger ||= build_logger
+    end
+
+    # 注入自定义 logger（例如 Rails.logger）。设为 nil 可触发下次重建。
+    attr_writer :logger
+
+    # 重建默认 logger（切换 log_format 后调用）
+    def reset_logger!
+      @logger = nil
     end
 
     def new_api(config = nil)
-      if config
-        K3cloud::K3cloudApi.new(config)
+      config ? K3cloud::K3cloudApi.new(config) : default_api
+    end
+
+    # 默认账号客户端（带缓存；传入新 config 不会污染此处）
+    def default_api
+      @default_api ||= K3cloud::K3cloudApi.new
+    end
+
+    # 测试/重新配置时重置默认客户端
+    def reset_default_api!
+      @default_api = nil
+    end
+
+    API_METHODS = %i[
+      draft save batch_save submit audit un_audit view execute_bill_query delete cancel_assign push execute_operation
+      allocate cancel_allocate group_save query_group_info group_delete attachment_upload attachment_download
+      query_business_info get_sys_report_data flex_save send_msg disassembly workflow_audit switch_org
+    ].freeze
+
+    def_delegators :default_api, *API_METHODS
+
+    private
+
+    def build_logger
+      logger = ::Logger.new($stderr)
+      logger.formatter = method(:format_log)
+      logger
+    end
+
+    # 根据 Configuration.default.log_format 决定输出：:text（默认）或 :json
+    def format_log(severity, datetime, _progname, msg)
+      if Configuration.default.log_format == :json
+        format_log_json(severity, datetime, msg)
       else
-        @default_api ||= K3cloud::K3cloudApi.new
+        format_log_text(severity, datetime, msg)
       end
     end
 
-    def_delegators :new_api, :draft, :save, :batch_save, :submit, :audit, :un_audit, :view, :execute_bill_query, :delete,
-                   :cancel_assign, :push, :execute_operation, :allocate, :cancel_allocate, :group_save, :query_group_info,
-                   :group_delete, :attachment_upload, :attachment_download, :query_business_info, :get_sys_report_data,
-                   :flex_save, :send_msg, :disassembly, :workflow_audit, :switch_org
+    def format_log_json(severity, datetime, msg)
+      payload = msg.is_a?(Hash) ? msg.dup : { msg: msg.to_s }
+      payload[:level] = severity
+      payload[:time] = datetime.strftime("%Y-%m-%dT%H:%M:%S.%L")
+      "#{payload.to_json}\n"
+    end
+
+    def format_log_text(severity, datetime, msg)
+      body = msg.is_a?(Hash) ? msg.inspect : msg.to_s
+      format("%s, [%s#%d] %5s -- %s\n", severity[0..0],
+             datetime.strftime("%Y-%m-%dT%H:%M:%S.%L"), Process.pid, severity, body)
+    end
   end
 end

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: k3cloud-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.5.0
 platform: ruby
 authors:
 - zevinto
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Ruby Gem for K3cloud OpenApi that uses cryptographic signature technology
+description: Ruby Gem for K3cloud OpenApi. Uses cryptographic signature technology
   to avoid plaintext transmission of keys and enables automatic login.
 email:
 - zevinto@163.com
@@ -49,7 +48,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/zevinto/k3cloud-sdk
-post_install_message:
+  source_code_uri: https://github.com/zevinto/k3cloud-sdk
+  changelog_uri: https://github.com/zevinto/k3cloud-sdk/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/zevinto/k3cloud-sdk/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -57,15 +58,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby Gem for K3cloud API.
 test_files: []