kingdee_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 934391e85b391da659c8495785ac56eca320131a646f6e268e2a590d5bd55ef4
+  data.tar.gz: 41fad52c3356633f04bc7409acfa42be1576597f5d17302b27c22d59c4629d3b
+SHA512:
+  metadata.gz: d51d6d431c9a39f77f121086f527cf5903e65f3fec8bf7a07394c57e7767596fdb3d5b1de9b8734e617c38ce1786c5e537fb2287a1bd3838b7ed61f9762490a2
+  data.tar.gz: 05dc1efb059ab4e576b5855539d86e56f11cfdba2093c96594cc5351a33e6b5d185bc52a3c9c60926f5ead6c12963d526d50114fb0f465695567f7f0b67123b4

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-03-27
+
+### Added
+- Modular configuration, signing, request builder, response parser and HTTP adapter.
+- Env-based configuration with `KingdeeApi.configure`, temporary overrides, and fine-grained timeouts.
+- Multipart uploads, deterministic signature helper, and a tested client facade.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 钟声
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# KingdeeApi
+
+一个用于实现金蝶云 API HTTP 请求加签的 Ruby gem。该 gem 提供了便捷的方式来调用金蝶云开放平台的 API，自动处理请求签名和认证。
+
+[金蝶云 API 文档](https://open.jdy.com/#/files/api/detail?index=3&categrayId=3cc8ee9a663e11eda5c84b5d383a2b93&id=adfe4a24712711eda0b307c6992ee459)
+
+## 功能特性
+
+- 🔐 自动处理 API 请求签名
+- 🔑 支持环境变量和代码配置两种方式
+- 📦 支持 GET、POST 等多种 HTTP 方法
+- 📎 支持文件上传功能
+- 🚀 简单易用的 API 接口
+- 🧩 模块化设计，配置、签名、请求和响应组件彼此解耦
+
+## 安装
+
+### 使用 Bundler
+
+在 `Gemfile` 中添加：
+
+```ruby
+gem 'kingdee_api'
+```
+
+然后执行：
+
+```bash
+bundle install
+```
+
+或者直接使用：
+
+```bash
+bundle add kingdee_api
+```
+
+### 直接安装
+
+如果未使用 Bundler 管理依赖，可以直接安装：
+
+```bash
+gem install kingdee_api
+```
+
+## 使用
+
+### 配置
+
+#### 方式一：使用环境变量（推荐）
+
+默认使用环境变量进行配置，适合生产环境使用：
+
+```bash
+# 设置环境变量
+export KINGDEE_CLIENT_ID=327910
+export KINGDEE_CLIENT_SECRET=327xxxxxxx910
+export KINGDEE_APP_KEY=gsKeflPn
+export KINGDEE_APP_SECRET=4bf00ef4c9252e4c727f0e9d762a706d418f5e87
+export KINGDEE_DOMAIN=https://tf.jdy.com
+```
+
+#### 方式二：初始化时集中配置
+
+在应用启动阶段调用 `KingdeeApi.configure`，可以将配置集中管理，同时保留在任意位置创建客户端的能力：
+
+```ruby
+KingdeeApi.configure do |config|
+  config.client_id = '327910'
+  config.client_secret = '327xxxxxxx910'
+  config.app_key = 'gsKeflPn'
+  config.app_secret = '4bf00ef4c9252e4c727f0e9d762a706d418f5e87'
+  config.domain = 'https://tf.jdy.com'
+  config.read_timeout = 20
+  config.open_timeout = 5
+end
+
+client = KingdeeApi.client # 任何需要的地方都可以拿到配置好的客户端
+```
+
+#### 方式三：临时配置某些参数
+
+当少量参数需要按需覆盖时，将它们直接传给 `client` 方法即可：
+
+```ruby
+client = KingdeeApi.client(domain: 'https://api.kingdee.com')
+```
+
+### 配置参数说明
+
+| 参数 | 说明 | 是否必填 |
+|------|------|----------|
+| `client_id` | 客户端 ID | 是 |
+| `client_secret` | 客户端密钥 | 是 |
+| `app_key` | 应用 Key | 是 |
+| `app_secret` | 应用密钥 | 是 |
+| `domain` | API 域名，如 `https://tf.jdy.com` 或 `https://api.kingdee.com` | 是 |
+
+### API 调用示例
+
+#### GET 请求示例 - 采购申请单列表
+
+用途说明：获取采购申请单列表  
+请求方式：GET  
+请求地址：`https://api.kingdee.com/jdy/v2/scm/pur_request`
+
+```ruby
+# 基本调用
+response = KingdeeApi.client.get('jdy/v2/scm/pur_request')
+
+# 带查询参数
+response = KingdeeApi.client.get('jdy/v2/scm/pur_request', params: {
+  page: 1,
+  page_size: 20,
+  filter: '...'
+})
+```
+
+#### POST 请求示例 - 采购申请单保存
+
+用途说明：采购申请单新增及修改。审核、删除等详见通用操作接口  
+请求方式：POST  
+请求地址：`https://api.kingdee.com/jdy/v2/scm/pur_request`
+
+```ruby
+# 基本 POST 请求
+response = KingdeeApi.client.post('jdy/v2/scm/pur_request', params: {
+  bill_date: '2024-01-01',
+  # 其他参数...
+})
+
+# 带文件上传的 POST 请求
+response = KingdeeApi.client.post('jdy/v2/scm/pur_request', params: {
+  bill_date: '2024-01-01',
+  # 其他参数...
+}) do |request|
+  request.attach 'file/path/1'
+  request.attach 'file/path/2'
+end
+```
+
+#### 其他 HTTP 方法
+
+```ruby
+# PUT 请求
+response = KingdeeApi.client.put('jdy/v2/scm/pur_request', params: { ... })
+
+# DELETE 请求
+response = KingdeeApi.client.delete('jdy/v2/scm/pur_request', params: { ... })
+
+# PATCH 请求
+response = KingdeeApi.client.patch('jdy/v2/scm/pur_request', params: { ... })
+```
+
+### 请求选项与高级用法
+
+- `query:`：强制附加查询字符串（POST/PUT 等也适用）。
+- `headers:`：追加自定义请求头。
+- `timeout:`：覆盖单次请求的 `open_timeout/read_timeout`。
+- `&block`：获取请求构建器并调用 `attach` 方法添加一个或多个文件。也可以通过 `attach(nil, data: '...', filename: 'a.txt')` 传入内存数据。
+
+### 响应处理
+
+```ruby
+response = KingdeeApi.client.get('jdy/v2/scm/pur_request')
+
+if response.success?
+  response.body # => Hash / Array（自动 JSON 解析）
+else
+  warn response.error_message || "请求失败: #{response.status}"
+end
+```
+
+## 开发
+
+### 环境设置
+
+克隆仓库后，运行以下命令安装依赖：
+
+```bash
+bin/setup
+```
+
+### 运行测试
+
+```bash
+rake test
+```
+
+### 交互式控制台
+
+可以使用交互式控制台进行实验：
+
+```bash
+bin/console
+```
+
+### 本地安装
+
+将 gem 安装到本地机器：
+
+```bash
+bundle exec rake install
+```
+
+### 发布新版本
+
+1. 更新 `lib/kingdee_api/version.rb` 中的版本号
+2. 运行发布命令：
+
+```bash
+bundle exec rake release
+```
+
+这将创建 git 标签、推送提交和标签，并将 `.gem` 文件推送到 [rubygems.org](https://rubygems.org)。
+
+## 常见问题
+
+### Q: 如何获取 API 凭证？
+
+A: 请登录金蝶云开放平台，在应用管理中创建应用并获取相应的 `client_id`、`client_secret`、`app_key` 和 `app_secret`。
+
+### Q: 支持哪些环境？
+
+A: 支持金蝶云的生产环境和测试环境，通过 `domain` 参数配置不同的环境地址。
+
+### Q: 如何处理请求错误？
+
+A: 检查响应状态码和错误信息，根据金蝶云 API 文档中的错误码进行处理。
+
+## Contributing
+
+欢迎提交 Bug 报告和 Pull Request！
+
+项目地址：[https://github.com/zhongsheng/kingdee_api](https://github.com/zhongsheng/kingdee_api)
+
+## License
+
+该 gem 基于 [MIT License](https://opensource.org/licenses/MIT) 开源协议发布。

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/kingdee_api/client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  class Client
+    SUPPORTED_METHODS = %i[get post put patch delete].freeze
+
+    include Signature
+    include Request
+
+    attr_reader :configuration
+    attr_reader :app_key
+    attr_reader :app_secret
+    attr_reader :client_id
+    attr_reader :client_secret
+    attr_reader :domain
+
+    def token
+      @token ||= get_token
+    end
+
+    def initialize(configuration, signer: nil, http_adapter: nil)
+      @configuration = coerce_configuration(configuration)
+      @configuration.validate!
+      @app_key = configuration.app_key
+      @app_secret = configuration.app_secret
+      @client_id = configuration.client_id
+      @client_secret = configuration.client_secret
+      @domain = configuration.domain
+    end
+
+
+
+    private
+
+    attr_reader :configuration, :signer, :http_adapter
+
+    def coerce_configuration(config)
+      return config if config.is_a?(Configuration)
+
+      Configuration.new.apply!(config || {})
+    end
+  end
+end

data/lib/kingdee_api/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  class Configuration
+    DEFAULT_DOMAIN = "https://api.kingdee.com"
+    ATTRIBUTES = %i[
+      client_id
+      client_secret
+      app_key
+      app_secret
+      domain
+      open_timeout
+      read_timeout
+      logger
+    ].freeze
+    REQUIRED = %i[client_id client_secret app_key app_secret domain].freeze
+
+    attr_accessor :client_id, :client_secret, :app_key, :app_secret, :logger
+    attr_reader :domain, :open_timeout, :read_timeout
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      self.client_id = ENV["KINGDEE_CLIENT_ID"]
+      self.client_secret = ENV["KINGDEE_CLIENT_SECRET"]
+      self.app_key = ENV["KINGDEE_APP_KEY"]
+      self.app_secret = ENV["KINGDEE_APP_SECRET"]
+      self.domain = ENV["KINGDEE_DOMAIN"]
+      self.open_timeout = ENV.fetch("KINGDEE_OPEN_TIMEOUT", 5)
+      self.read_timeout = ENV.fetch("KINGDEE_READ_TIMEOUT", 30)
+      self.logger = nil
+    end
+
+    def dup
+      self.class.new.apply!(to_h)
+    end
+    alias clone dup
+
+    def apply!(attributes)
+      return self if attributes.nil?
+
+      attributes.each do |key, value|
+        writer = "#{key}="
+        next unless respond_to?(writer)
+
+        public_send(writer, value)
+      end
+      self
+    end
+
+    def to_h
+      ATTRIBUTES.each_with_object({}) do |key, memo|
+        value = public_send(key)
+        memo[key] = value unless value.nil?
+      end
+    end
+
+    def validate!
+      missing = REQUIRED.reject { |name| present?(public_send(name)) }
+      return true if missing.empty?
+
+      raise ConfigurationError, "Missing configuration: #{missing.join(', ')}"
+    end
+
+    def domain=(value)
+      sanitized = value.to_s.strip
+      sanitized = nil if sanitized.empty?
+      sanitized ||= DEFAULT_DOMAIN
+      @domain = sanitized.chomp("/")
+    end
+
+    def open_timeout=(value)
+      @open_timeout = normalize_timeout(value, default: 5)
+    end
+
+    def read_timeout=(value)
+      @read_timeout = normalize_timeout(value, default: 30)
+    end
+
+    private
+
+    def normalize_timeout(value, default:)
+      Integer(value)
+    rescue ArgumentError, TypeError
+      default
+    end
+
+    def present?(value)
+      !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+    end
+  end
+end

data/lib/kingdee_api/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class RequestError < Error; end
+end

data/lib/kingdee_api/request.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  module Request
+    HOST = 'https://api.kingdee.com'
+
+    def get(path, params = nil)
+      query_with('GET', path: path, params: params)
+    end
+
+    def post
+    end
+
+    private
+    def query_with(method, path:, params: nil)
+      # ✅ 构造请求 URL
+      uri = URI("#{HOST}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.nil?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      x_api_signature = x_api_signature_with(
+        method: method,
+        path: path,
+        params: params,
+        nonce: nonce,
+        timestamp: timestamp,
+        client_secret: client_secret
+      )
+
+      request_class = Net::HTTP.const_get(method.capitalize)
+      request = request_class.new(uri)
+      request["Content-Type"] = "application/json"
+      request["X-Api-ClientID"]     = client_id
+      request["X-Api-Auth-Version"] = "2.0"
+      request["X-Api-TimeStamp"]    = timestamp
+      request["X-Api-SignHeaders"]  = "X-Api-TimeStamp,X-Api-Nonce"
+      request["X-Api-Nonce"]        = nonce
+      request["X-Api-Signature"]    = "#{x_api_signature}"
+      request["app-token"]    = token
+      request["X-GW-Router-Addr"] = domain
+
+      response = http.request(request)
+
+      pp response.body
+      puts "[HTTP] #{response.code}"
+      # puts JSON.parse(response.body)
+      # app-token: object	false	用于调用星辰接口，有效期为24小时
+      response.body
+    end
+  end
+end

data/lib/kingdee_api/response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  class Response
+    attr_reader :status, :body, :headers
+
+    def initialize(http_response)
+      @status = http_response.code.to_i
+      @headers = extract_headers(http_response)
+      @raw_body = http_response.body
+      @body = parse_body(@raw_body)
+    end
+
+    def success?
+      (200..299).include?(status)
+    end
+
+    def error_message
+      return nil if success?
+
+      if body.is_a?(Hash)
+        body["message"] || body["msg"] || body["error"] || body["error_description"]
+      end
+    end
+
+    def raw_body
+      @raw_body
+    end
+
+    private
+
+    def parse_body(payload)
+      return nil if payload.nil? || payload.empty?
+
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      payload
+    end
+
+    def extract_headers(response)
+      response.each_header.each_with_object({}) do |(key, value), memo|
+        memo[key] = value
+      end
+    end
+  end
+end

data/lib/kingdee_api/signature.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  module Signature
+
+    SIGN_PATH = '/jdyconnector/app_management/kingdee_auth_token'
+    TOKEN_CACHE_TTL = 24 * 60 * 60 # 24小时，单位：秒
+
+    def get_token
+      # 检查缓存是否有效
+      cached_token = get_cached_token
+      return cached_token if cached_token
+
+      # 缓存无效或不存在，获取新token
+      app_signature = app_signature_with
+      params = {
+        "app_key"       => app_key,
+        "app_signature" => app_signature
+      }
+      x_api_signature = x_api_signature_with(
+        method: 'GET',
+        path: SIGN_PATH,
+        params: params,
+        nonce: nonce,
+        timestamp: timestamp,
+        client_secret: client_secret
+      )
+
+      token = query_token_with(app_signature, x_api_signature)
+      # 缓存token
+      cache_token(token)
+      token
+    end
+
+    private
+    def query_token_with(app_signature, x_api_signature)
+      # ✅ 构造请求 URL
+      uri = URI('https://api.kingdee.com/jdyconnector/app_management/kingdee_auth_token')
+      uri.query = URI.encode_www_form({
+                                        "app_key"       => app_key,
+                                        "app_signature" => app_signature #app_signature
+                                      })
+
+      pp uri.query
+      pp uri.host
+      pp uri.to_s
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Get.new(uri)
+      request["X-Api-ClientID"]     = client_id
+      request["X-Api-Auth-Version"] = "2.0"
+      request["X-Api-TimeStamp"]    = timestamp
+      request["X-Api-Nonce"]        = nonce
+      request["X-Api-SignHeaders"]  = "X-Api-TimeStamp,X-Api-Nonce"
+      request["X-Api-Signature"]    = "#{x_api_signature}"
+
+
+
+      response = http.request(request)
+
+      puts "[HTTP] #{response.code}"
+      puts JSON.parse(response.body)
+      # app-token: object	false	用于调用星辰接口，有效期为24小时
+      JSON.parse(response.body)["data"]["app-token"]
+    end
+
+
+
+    def x_api_signature_with(method:, path:, params:, nonce:, timestamp:, client_secret:)
+      encoded_path = URI.encode_www_form_component(path)
+
+      if params.nil? || params.empty?
+        encoded_params = ''
+      else
+      encoded_params = params.sort.to_h.map do |k, v|
+        "#{double_encode(k)}=#{double_encode(v)}"
+      end.join("&")
+    end
+
+      headers_block = [
+        "x-api-nonce:#{nonce}",
+        "x-api-timestamp:#{timestamp}"
+      ].join("\n")
+
+      sign_plain = [
+        method.upcase,
+        encoded_path,
+        encoded_params,
+        headers_block,
+        "" # ⚠️ 末尾必须换行
+      ].join("\n")
+
+      puts sign_plain
+
+
+      Base64.strict_encode64(
+        OpenSSL::HMAC.hexdigest("SHA256", client_secret, sign_plain)
+      )
+    end
+    def nonce
+      @nonce ||= (Time.now.to_f * 1000).to_i.to_s
+    end
+
+    def timestamp
+      @timestamp ||= (Time.now.to_f * 1000).to_i.to_s
+    end
+
+    def app_signature_with
+      Base64.strict_encode64(
+        OpenSSL::HMAC.hexdigest("SHA256", app_secret, app_key)
+      )
+    end
+
+    def double_encode(str)
+      URI.encode_www_form_component(
+        URI.encode_www_form_component(str)
+      ).gsub(/%[0-9a-f]{2}/) { |m| m.upcase }
+    end
+
+    def cache_token(token)
+      @token_cache = {
+        token: token,
+        cached_at: Time.now
+      }
+    end
+
+    def get_cached_token
+      return nil unless @token_cache
+
+      cached_at = @token_cache[:cached_at]
+      return nil unless cached_at
+
+      # 检查是否过期（24小时）
+      elapsed_time = Time.now - cached_at
+      return nil if elapsed_time >= TOKEN_CACHE_TTL
+
+      @token_cache[:token]
+    end
+
+  end
+end

data/lib/kingdee_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module KingdeeApi
+  VERSION = "0.1.0"
+end

data/lib/kingdee_api.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "openssl"
+require "base64"
+require "securerandom"
+require "digest"
+
+require_relative "kingdee_api/version"
+require_relative "kingdee_api/errors"
+require_relative "kingdee_api/configuration"
+require_relative "kingdee_api/signature"
+
+require_relative "kingdee_api/request"
+require_relative "kingdee_api/response"
+
+require_relative "kingdee_api/client"
+
+module KingdeeApi
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+
+    def client(options = nil, **overrides)
+      config = build_configuration(options, overrides)
+      Client.new(config)
+    end
+
+    private
+
+    def build_configuration(options, overrides)
+      case options
+      when Configuration
+        options.dup
+      when Hash
+        configuration.dup.apply!(options.merge(overrides))
+      else
+        overrides.empty? ? configuration.dup : configuration.dup.apply!(overrides)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: kingdee_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 钟声
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight, modular Ruby client that signs and sends HTTP requests
+  to the Kingdee Cloud (Jingdian) open platform.
+email:
+- 444133866@qq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/kingdee_api.rb
+- lib/kingdee_api/client.rb
+- lib/kingdee_api/configuration.rb
+- lib/kingdee_api/errors.rb
+- lib/kingdee_api/request.rb
+- lib/kingdee_api/response.rb
+- lib/kingdee_api/signature.rb
+- lib/kingdee_api/version.rb
+homepage: https://github.com/zhongsheng/kingdee_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zhongsheng/kingdee_api
+  source_code_uri: https://github.com/zhongsheng/kingdee_api
+  changelog_uri: https://github.com/zhongsheng/kingdee_api/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Authenticated HTTP client for the Kingdee Cloud API.
+test_files: []