coordconver 0.1.3 → 1.1.0

data/lib/coordconver/degree.rb

@@ -1,60 +1,57 @@
-module Coordconver
-	module Degree
-		def self.included(base)
-			base.extend(ClassMethods)
-		end
-
-		module ClassMethods
-
-			# 取整数位
-			def num(n)
-				n.to_i
-			end
-
-			# 取小数数位 Decimal digit
-			def dig(n)
-				n.to_f-num(n)
-			end
-
-			# 计算分
-			def min(n)
-				dig(n)*60
-			end
-
-			# 计算秒
-			def sec(n)
-				(min(n)-num(min(n)))*60
-			end
-
-			# 坐标转度数
-			def degree(lng, lat)
-				[cal_degree(lng),cal_degree(lat)]
-			end
+# frozen_string_literal: true
 
-			def cal_degree(n)
-				"#{num(n)}°#{num(min(n))}′#{num(sec(n))}″"
-			end
-
-
-			# 获取分
-			def get_min(n)
-				n.split('°').last.to_f
-			end
-
-			# 获取秒
-			def get_sec(n)
-				n.split('′').last.to_f
-			end
-
-			# 度数转坐标
-			def cal_undegree(n)
-				(num(n) + get_min(n)/60 + get_sec(n)/3600).round(5)
-			end
-
-			def undegree(lng, lat)
-				[cal_undegree(lng),cal_undegree(lat)]
-			end
-
-		end
-	end
+# 经纬度(十进制度)与度分秒(DMS)互转。
+#
+# 经 Coordconver.extend(Degree) 挂载, 以下两种写法等价:
+#   Coordconver.degree(38.65777, 104.08296)
+#   Coordconver::Degree.degree(38.65777, 104.08296)
+module Coordconver
+  module Degree
+    extend self
+
+    # 坐标转度分秒, 返回 [经度, 纬度] 的 DMS 字符串。
+    # 负值按西经/南纬处理, 取绝对值后再格式化。
+    # Coordconver.degree(38.65777, 104.08296) # => ["38°39′27.97″", "104°4′58.66″"]
+    def degree(lng, lat)
+      [cal_degree(lng), cal_degree(lat)]
+    end
+
+    # 单个十进制度数转度分秒字符串, 默认保留两位小数秒。
+    # Coordconver.cal_degree(38.65777)    # => "38°39′27.97″"
+    # Coordconver.cal_degree(38.65777, 0) # => "38°39′27″"
+    def cal_degree(n, precision = 2)
+      sign = n.negative? ? "-" : ""
+      n = n.abs
+      d = n.to_i
+      m = (n - d) * 60
+      s = (m - m.to_i) * 60
+      if precision.zero?
+        "#{sign}#{d}°#{m.to_i}′#{s.round}″"
+      else
+        "#{sign}#{d}°#{m.to_i}′#{s.round(precision)}″"
+      end
+    end
+
+    # 度分秒转坐标, 返回 [经度, 纬度] 浮点值。
+    # 兼容 "38°39′27.97″"、"38°39′27.97""、"38d39m27.97s"、"38:39:27.97" 等写法。
+    # Coordconver.undegree("38°39′27.97″", "104°4′58.66″") # => [38.65777, 104.08296]
+    def undegree(lng, lat)
+      [cal_undegree(lng), cal_undegree(lat)]
+    end
+
+    # 单个度分秒字符串转十进制度数。
+    # Coordconver.cal_undegree("104°4′58.66″") # => 104.08296
+    # Coordconver.cal_undegree("-38°39′27.97″") # => -38.65777
+    def cal_undegree(str)
+      parts = str.to_s.scan(/[-+]?\d+(?:\.\d+)?/)
+      return 0.0 if parts.empty?
+
+      deg, min, sec = parts.map(&:to_f)
+      min ||= 0.0
+      sec ||= 0.0
+      value = deg.abs + min / 60.0 + sec / 3600.0
+      value = -value if str.to_s =~ /^\s*[-–]/ || deg.negative?
+      value.round(6)
+    end
+  end
 end

data/lib/coordconver/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coordconver
+  # 统一错误基类, 便于业务侧 rescue Coordconver::Error
+  class Error < StandardError; end
+
+  # 缺少 API key 等配置问题时抛出
+  class ConfigurationError < Error; end
+
+  # 网络超时、连接失败、响应非 JSON 时抛出
+  class NetworkError < Error; end
+
+  # 服务端返回业务错误(如 key 无效、配额超限)时抛出
+  class ApiError < Error
+    attr_reader :code, :raw
+
+    def initialize(message = nil, code: nil, raw: nil)
+      super(message)
+      @code = code
+      @raw = raw
+    end
+  end
+end

data/lib/coordconver/formats.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+
+# WKT / GeoJSON 与坐标互转。
+# 经 Coordconver.extend(Formats) 挂载:
+#   Coordconver.parse_wkt("POINT (121.47 31.25)")    # => [121.47, 31.25]
+#   Coordconver.to_wkt(121.47, 31.25)                # => "POINT (121.47 31.25)"
+#   Coordconver.to_geojson(121.47, 31.25)            # => {"type"=>"Point", "coordinates"=>[121.47, 31.25]}
+module Coordconver
+  module Formats
+    extend self
+
+    # 解析 WKT 点: "POINT (121.47 31.25)" / "POINT(121.47 31.25)" -> [lng, lat]
+    def parse_wkt(wkt)
+      match = wkt.to_s.match(/point\s*z?m?\s*\(\s*([+-]?\d+(?:\.\d+)?)\s+([+-]?\d+(?:\.\d+)?)/i)
+      raise ArgumentError, "无法解析 WKT: #{wkt.inspect} (仅支持 POINT)" unless match
+
+      [match[1].to_f, match[2].to_f]
+    end
+
+    # 生成 WKT 点
+    def to_wkt(lng, lat)
+      "POINT (#{lng} #{lat})"
+    end
+
+    # 解析 GeoJSON: 接受 Hash 或 JSON 字符串。
+    # 支持 Point 与包着 Point 的 Feature。
+    # 返回 [lng, lat]
+    def parse_geojson(input)
+      obj = input.is_a?(Hash) ? input : JSON.parse(input.to_s)
+      obj = obj["geometry"] if obj["type"] == "Feature"
+      raise ArgumentError, "仅支持 GeoJSON Point, 实际: #{obj['type'].inspect}" unless obj["type"] == "Point"
+
+      coords = obj["coordinates"]
+      raise ArgumentError, "GeoJSON Point 缺少 coordinates" unless coords.is_a?(Array) && coords.size >= 2
+
+      [coords[0].to_f, coords[1].to_f]
+    end
+
+    # 生成 GeoJSON Point Hash (GeoJSON 规范中坐标为 [lng, lat] 顺序)
+    def to_geojson(lng, lat)
+      { "type" => "Point", "coordinates" => [lng, lat] }
+    end
+
+    # 生成 GeoJSON Point JSON 字符串
+    def to_geojson_string(lng, lat)
+      JSON.generate(to_geojson(lng, lat))
+    end
+  end
+end

data/lib/coordconver/geo/api.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 百度/高德/腾讯 API 的统一调度层:
+    # 组装 key -> LRU 缓存 -> 请求 -> 识别 key 类失败 -> 轮换下一个 key 重试。
+    module Api
+      # provider:    :baidu / :gaode / :tencent
+      # params:      业务参数(不含 key)
+      # key_param:   key 参数名 (:ak / :key)
+      # sign:        可选 Proc, 对含 key 的完整参数做签名(百度 SN 校验)
+      # bad_result:  Proc, 判断响应是否属于"key 无效/配额超限"类失败(应轮换 key)
+      def self.call(provider:, url:, params:, key_param:, sign: nil, bad_result:)
+        keys = Configuration.keys_for(provider)
+        attempts = 0
+        loop do
+          key = KeyPool.next_key(provider, keys)
+          full_params = params.merge(key_param => key)
+          full_params = sign.call(full_params) if sign
+          cache_key = [provider, url, full_params]
+
+          hit = Cache.get(cache_key)
+          if hit
+            return hit unless bad_result.call(hit)
+
+            Cache.delete(cache_key) # 防御: 不应缓存过失败响应
+            next
+          end
+
+          response = Utils::Request.get(url, params: full_params)
+          return Cache.set(cache_key, response) unless bad_result.call(response)
+
+          KeyPool.mark_bad(provider, key)
+          attempts += 1
+          if attempts >= keys.size
+            raise ApiError.new(
+              "#{provider} 请求失败: 所有 #{keys.size} 个 key 均无效或配额超限",
+              code: provider, raw: response
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coordconver/geo/baidu.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Coordconver
+  module Geo
+    # 百度地图 Web 服务 API (Geocoding API v3)
+    # 申请 key: https://lbsyun.baidu.com/apiconsole/key
+    # 建议创建"服务端"类型 AK 并配置 IP 白名单; 若 AK 类型为"SN 校验", 需同时配置 baidu_sn
+    module Baidu
+      extend self
+
+      # 视为"key 无效/配额超限"的状态码, 触发自动轮换下一个 key
+      # 200 AK不存在 201 AK被禁用 210 AK参数错误 401 配额超限 402 每秒请求量超限
+      KEY_ERROR_STATUSES = [200, 201, 210, 401, 402].freeze
+
+      # 地理编码: 结构化地址 -> 坐标
+      # Coordconver::Baidu.geo("百度大厦")["result"]["location"] # => {"lng"=>116.30..., "lat"=>40.05...}
+      # 支持可选参数: city(城市名), ret_coordtype(返回坐标类型, 默认 bd09ll)
+      def geo(address, options = {})
+        params = {
+          address: address,
+          output: "json"
+        }.merge(options)
+        request("/geocoding/v3/", params)
+      end
+
+      # 逆地理编码: 坐标 -> 结构化地址
+      # Coordconver::Baidu.regeo(116.322987, 39.983424)["result"]["formatted_address"]
+      # options: coordtype(输入坐标类型, 默认 bd09ll, 可选 wgs84ll / gcj02ll 等)
+      def regeo(lng, lat, options = {})
+        params = {
+          location: "#{lat},#{lng}",
+          output: "json",
+          coordtype: "bd09ll"
+        }.merge(options)
+        request("/reverse_geocoding/v3/", params)
+      end
+
+      # IP 定位: IP -> 城市 + 坐标 (BD-09)
+      def ip(ip = nil)
+        params = { coor: "bd09ll", output: "json" }
+        params[:ip] = ip unless ip.nil? || ip.empty?
+        request("/location/ip", params)
+      end
+
+      # 便捷方法: 地址 -> [lng, lat] (BD-09), 解析失败返回 nil
+      def geo_location(address, options = {})
+        loc = geo(address, options).dig("result", "location")
+        loc && [loc["lng"], loc["lat"]]
+      end
+
+      # 便捷方法: 坐标 -> 地址字符串 (BD-09), 解析失败返回 nil
+      def regeo_address(lng, lat, options = {})
+        regeo(lng, lat, options).dig("result", "formatted_address")
+      end
+
+      private
+
+      def request(path, params)
+        sn_key = Configuration.settings[:baidu_sn]
+        Api.call(
+          provider: :baidu,
+          url: base_url + path,
+          params: params,
+          key_param: :ak,
+          sign: sn_key ? ->(p) { p.merge(sn: sn(path, p, sn_key)) } : nil,
+          bad_result: ->(r) { KEY_ERROR_STATUSES.include?(r["status"].to_i) }
+        )
+      end
+
+      def base_url
+        Configuration.settings[:baidu_base_url].sub(%r{/\z}, "")
+      end
+
+      # SN 校验: sn = md5(urlencode(path + "?" + 按参数名字典序拼接的 query + sk))
+      def sn(path, params, sk)
+        query = params.sort.map { |k, v| "#{k}=#{v}" }.join("&")
+        Digest::MD5.hexdigest(custom_uri_encode("#{path}?#{query}") + sk)
+      end
+
+      # 百度 SN 校验要求的 URI 编码: 仅 A-Za-z0-9-_.~ 不编码, 其余按字节转 %XX 大写
+      def custom_uri_encode(str)
+        str.gsub(/[^A-Za-z0-9\-_.~]/) do |char|
+          char.bytes.map { |b| format("%%%02X", b) }.join
+        end
+      end
+    end
+  end
+end

data/lib/coordconver/geo/cache.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 进程内 LRU + TTL 缓存, 用于地理编码结果去重以节省配额。
+    # 默认关闭, 通过 config.cache = true 开启; 可配置 cache_ttl / cache_size。
+    module Cache
+      DEFAULT_TTL = 3600
+      DEFAULT_SIZE = 1024
+
+      @store = {}
+      @mutex = Mutex.new
+
+      class << self
+        def enabled?
+          Configuration.configured? && Configuration.settings[:cache] ? true : false
+        end
+
+        # 命中且未过期返回值, 否则返回 nil
+        def get(key)
+          return nil unless enabled?
+
+          @mutex.synchronize do
+            entry = @store[key]
+            return nil unless entry
+            return nil if Time.now - entry[:at] > ttl
+
+            @store.delete(key)
+            @store[key] = entry # LRU: 重新插入到队尾
+            entry[:value]
+          end
+        end
+
+        # 存入并返回 value; 未启用时原样返回 value
+        def set(key, value)
+          return value unless enabled?
+
+          @mutex.synchronize do
+            @store.delete(key)
+            @store[key] = { at: Time.now, value: value }
+            @store.shift while @store.size > size
+            value
+          end
+        end
+
+        def delete(key)
+          @mutex.synchronize { @store.delete(key) }
+        end
+
+        def clear!
+          @mutex.synchronize { @store.clear }
+        end
+
+        private
+
+        def ttl
+          Configuration.settings[:cache_ttl] || DEFAULT_TTL
+        end
+
+        def size
+          Configuration.settings[:cache_size] || DEFAULT_SIZE
+        end
+      end
+    end
+  end
+end

data/lib/coordconver/geo/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 初始化配置。保留旧写法, 也可用 Coordconver.configure 块:
+    #   Coordconver::Client.new(["百度ak1", "百度ak2"], ["高德key1"])
+    class Client
+      def initialize(baidu_map_aks = [], gaode_map_keys = [], options = {})
+        Configuration.init(baidu_map_aks, gaode_map_keys, options)
+      end
+    end
+  end
+
+  module_function
+
+  # 全局配置块:
+  #   Coordconver.configure do |config|
+  #     config.baidu_map_aks = ["ak1"]
+  #     config.gaode_map_keys = ["key1"]
+  #   end
+  def configure
+    Geo::Configuration.init unless Geo::Configuration.configured?
+    yield Geo::Configuration
+  end
+end

data/lib/coordconver/geo/configuration.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 全局配置。支持两种写法:
+    #
+    #   # 推荐: 全局配置块, key 支持数组以实现多 key 轮询
+    #   Coordconver.configure do |config|
+    #     config.baidu_map_aks = ["你的百度ak1", "你的百度ak2"]
+    #     config.gaode_map_keys = ["你的高德key1", "你的高德key2"]
+    #     config.tencent_map_keys = ["你的腾讯key1"]
+    #     # 可选: 百度 SN 校验(仅当 AK 类型为"SN 校验"时需要), 服务端 AK 用 IP 白名单则无需配置
+    #     config.baidu_sn = "你的百度SK"
+    #     # 可选: 进程内缓存地理编码结果, 节省配额 (默认 false)
+    #     config.cache = true
+    #     config.cache_ttl = 3600      # 缓存秒数, 默认 3600
+    #     config.cache_size = 1024     # 缓存条目上限, 默认 1024 (LRU 淘汰)
+    #     # 可选: 超时(秒)
+    #     config.open_timeout = 5
+    #     config.read_timeout = 10
+    #   end
+    #
+    #   # 兼容旧写法
+    #   Coordconver::Client.new(["百度ak"], ["高德key"], tencent_map_keys: ["腾讯key"])
+    module Configuration
+      extend self
+
+      DEFAULT_MAP_OPTIONS = {
+        baidu_base_url: "https://api.map.baidu.com",
+        gaode_base_url: "https://restapi.amap.com/v3",
+        tencent_base_url: "https://apis.map.qq.com/ws",
+        open_timeout: 5,
+        read_timeout: 10,
+        cache: false,
+        cache_ttl: 3600,
+        cache_size: 1024
+      }.freeze
+
+      PROVIDER_KEY_FIELD = {
+        baidu: :baidu_map_aks,
+        gaode: :gaode_map_keys,
+        tencent: :tencent_map_keys
+      }.freeze
+
+      attr_reader :settings
+
+      def configured?
+        !@settings.nil?
+      end
+
+      def init(baidu_map_aks = nil, gaode_map_keys = nil, options = {})
+        tencent_keys = Array(options.delete(:tencent_map_keys))
+        @settings = DEFAULT_MAP_OPTIONS.merge(
+          baidu_map_aks: Array(baidu_map_aks).compact.reject(&:empty?),
+          gaode_map_keys: Array(gaode_map_keys).compact.reject(&:empty?),
+          tencent_map_keys: tencent_keys.compact.reject(&:empty?)
+        ).merge(options)
+        self
+      end
+
+      def reset!
+        @settings = nil
+        KeyPool.reset!
+        Cache.clear!
+      end
+
+      def [](key)
+        settings[key]
+      end
+
+      # 按 provider (:baidu/:gaode/:tencent) 取可用 key 数组, 未配置时抛出清晰错误
+      def keys_for(provider)
+        field = PROVIDER_KEY_FIELD[provider]
+        raise ArgumentError, "未知的服务商: #{provider.inspect}" unless field
+
+        keys = settings[field]
+        raise ConfigurationError, "未配置 #{provider} 的 key (#{field}), 请通过 Coordconver.configure 或 Coordconver::Client.new 设置" if keys.empty?
+
+        keys
+      end
+
+      def method_missing(name, *args)
+        if name.to_s.end_with?("=") && settings.key?(name.to_s.chomp("=").to_sym)
+          settings[name.to_s.chomp("=").to_sym] = args.first
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        (name.to_s.end_with?("=") && settings.key?(name.to_s.chomp("=").to_sym)) || super
+      end
+
+      def settings
+        @settings or raise ConfigurationError, "尚未配置地图 API key。请先执行 Coordconver.configure { |c| c.baidu_map_aks = [...]; c.gaode_map_keys = [...] } 或 Coordconver::Client.new([百度ak数组], [高德key数组])"
+      end
+
+      # 兼容旧接口: 取一个 key (现为实现为轮询)
+      def sample_baidu_ak
+        KeyPool.next_key(:baidu, keys_for(:baidu))
+      end
+
+      def sample_gaode_key
+        KeyPool.next_key(:gaode, keys_for(:gaode))
+      end
+
+      def sample_tencent_key
+        KeyPool.next_key(:tencent, keys_for(:tencent))
+      end
+    end
+  end
+end

data/lib/coordconver/geo/gaode.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 高德地图 Web 服务 API
+    # 申请 key: https://console.amap.com/dev/key/app (类型选"Web服务")
+    module Gaode
+      extend self
+
+      # 视为"key 无效/配额超限"的 infocode, 触发自动轮换下一个 key
+      # 10001 KEY不合法 10003 日调用量超限 10009 KEY类型错误 10044 超出支持范围 20003 日调用量超限
+      KEY_ERROR_INFOCODES = %w[10001 10003 10009 10044 20003].freeze
+
+      # 高德官方坐标转换接口支持的源坐标系
+      COORDSYS_MAP = {
+        gps: "gps", wgs84: "gps", wgs: "gps",
+        baidu: "baidu", bd09: "baidu", bd: "baidu",
+        gcj02: "autonavi", gcj: "autonavi", autonavi: "autonavi"
+      }.freeze
+
+      # 地理编码: 结构化地址 -> 坐标 (GCJ-02)
+      # Coordconver::Gaode.geo("北京方恒国际中心A座")["geocodes"][0]["location"] # => "116.480724,39.989584"
+      # 支持可选参数: city(城市名), citylimit, batch, ...
+      def geo(address, options = {})
+        params = { address: address }.merge(options)
+        request("/geocode/geo", params)
+      end
+
+      # 逆地理编码: 坐标 (GCJ-02) -> 结构化地址
+      # Coordconver::Gaode.regeo(116.480881, 39.989410)["regeocode"]["formatted_address"]
+      # options: extensions(base/all), radius, poitype, ...
+      def regeo(lng, lat, options = {})
+        params = { location: "#{lng},#{lat}" }.merge(options)
+        request("/geocode/regeo", params)
+      end
+
+      # 官方坐标转换 API: 将 GPS(WGS-84)/百度(BD-09) 坐标转换为高德坐标 (GCJ-02)。
+      # 与离线算法互为补充, 适合需要官方权威转换结果的场景。
+      # 单点或数组均可(最多 40 个点):
+      #   Coordconver::Gaode.convert([121.468738, 31.247138], from: :gps)
+      #   Coordconver::Gaode.convert([[121.46, 31.24], [116.39, 39.90]], from: :gps)
+      # 返回完整 JSON; from 支持 :gps(wgs84) / :baidu(bd09) / :gcj02
+      def convert(points, from: :gps)
+        coordsys = COORDSYS_MAP[from.to_s.downcase.to_sym]
+        raise ArgumentError, "不支持的源坐标系: #{from.inspect} (支持 :gps/:wgs84, :baidu/:bd09, :gcj02)" unless coordsys
+
+        list = normalize_point_list(points)
+        raise ArgumentError, "单次最多转换 40 个坐标点" if list.size > 40
+
+        params = {
+          locations: list.map { |pt| Coordconver.extract_pair(pt).join(",") }.join(";"),
+          coordsys: coordsys
+        }
+        request("/assistant/coordinate/convert", params)
+      end
+
+      # convert 的便捷版本, 返回 [[lng, lat], ...] (GCJ-02), 失败返回 nil
+      def convert_location(points, from: :gps)
+        resp = convert(points, from: from)
+        return nil unless resp["status"] == "1" && resp["locations"]
+
+        resp["locations"].split(";").map { |s| s.split(",").map(&:to_f) }
+      end
+
+      # 便捷方法: 地址 -> [lng, lat] (GCJ-02), 解析失败返回 nil
+      def geo_location(address, options = {})
+        resp = geo(address, options)
+        geocode = resp["geocodes"] && resp["geocodes"][0]
+        loc = geocode && geocode["location"]
+        return nil if loc.nil? || loc.empty?
+
+        loc.split(",").map(&:to_f)
+      end
+
+      # 便捷方法: 坐标 -> 地址字符串 (GCJ-02), 解析失败返回 nil
+      def regeo_address(lng, lat, options = {})
+        regeo(lng, lat, options).dig("regeocode", "formatted_address")
+      end
+
+      private
+
+      def normalize_point_list(points)
+        list = points.is_a?(Array) && points.first.is_a?(Numeric) ? [points] : Array(points)
+        raise ArgumentError, "未提供坐标点" if list.empty?
+
+        list
+      end
+
+      def request(path, params)
+        Api.call(
+          provider: :gaode,
+          url: base_url + path,
+          params: params,
+          key_param: :key,
+          bad_result: ->(r) { r["status"].to_s == "0" && KEY_ERROR_INFOCODES.include?(r["infocode"].to_s) }
+        )
+      end
+
+      def base_url
+        # 兼容旧版本以 /geocode 结尾的 base_url 配置
+        Configuration.settings[:gaode_base_url].sub(%r{/geocode/?\z}, "").sub(%r{/\z}, "")
+      end
+    end
+  end
+end