coordconver 0.1.4 → 1.1.0

data/lib/coordconver/geo/gaode.rb

@@ -1,49 +1,104 @@
+# frozen_string_literal: true
+
 module Coordconver
   module Geo
+    # 高德地图 Web 服务 API
+    # 申请 key: https://console.amap.com/dev/key/app (类型选"Web服务")
     module Gaode
       extend self
 
-      # Coordconver::Gaode.regeo(116.480881,39.989410)
-      # 116.480881,39.989410-->北京市朝阳区阜通东大街6号
-      def regeo(lng, lat)
-        url = regeo_url(lng, lat)
-        # params = {
-        #   key: gaode_map_key,
-        #   location: lng + "," + lat
-        # }
+      # 视为"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
 
-        Utils::Request.get(url, params: nil)
+      # 逆地理编码: 坐标 (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
 
-      # Coordconver::Gaode.geo("北京市朝阳区阜通东大街6号")
-      # 116.480881,39.989410-->北京市朝阳区阜通东大街6号
-      def geo(address)
-        url = geo_url
+      # 官方坐标转换 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 = {
-          key: gaode_map_key,
-          address: address
+          locations: list.map { |pt| Coordconver.extract_pair(pt).join(",") }.join(";"),
+          coordsys: coordsys
         }
+        request("/assistant/coordinate/convert", params)
+      end
 
-        Utils::Request.get(url, params: params)
+      # 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
 
-      private
+      # 便捷方法: 地址 -> [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?
 
-      def regeo_url(lng, lat)
-        base_url + '/regeo' + "?key=#{gaode_map_key}&location=#{lng},#{lat}"
+        loc.split(",").map(&:to_f)
       end
 
-      def geo_url
-        base_url + '/geo'
+      # 便捷方法: 坐标 -> 地址字符串 (GCJ-02), 解析失败返回 nil
+      def regeo_address(lng, lat, options = {})
+        regeo(lng, lat, options).dig("regeocode", "formatted_address")
       end
 
-      def base_url
-        Configuration.settings[:gaode_base_url]
+      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 gaode_map_key
-        Configuration.settings[:gaode_map_keys].sample
+      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

data/lib/coordconver/geo/key_pool.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 多 key 智能轮询: round-robin 取 key, 请求失败(配额超限/无效)时摘除该 key,
+    # 冷却时间过后自动恢复。线程安全。
+    class KeyPool
+      # 被摘除 key 的冷却时长(秒), 覆盖"每秒/每日配额超限"两类场景
+      COOLDOWN = 300
+
+      def initialize
+        @mutex = Mutex.new
+        @index = {}
+        @disabled_at = {}
+      end
+
+      # 轮询取下一个可用 key; 全部处于冷却期时抛出 ApiError
+      def next_key(provider, keys)
+        @mutex.synchronize do
+          purge_expired(Time.now)
+          enabled = keys.reject { |k| @disabled_at[[provider, k]] }
+          if enabled.empty?
+            raise ApiError, "所有 #{provider} key 均不可用(配额超限或无效), 请更换或补充 key"
+          end
+
+          @index[provider] = (@index[provider] ||= -1) + 1
+          enabled[@index[provider] % enabled.size]
+        end
+      end
+
+      def mark_bad(provider, key)
+        @mutex.synchronize { @disabled_at[[provider, key]] = Time.now }
+      end
+
+      def disabled?(provider, key)
+        @mutex.synchronize do
+          purge_expired(Time.now)
+          !@disabled_at[[provider, key]].nil?
+        end
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @index.clear
+          @disabled_at.clear
+        end
+      end
+
+      private
+
+      def purge_expired(now)
+        @disabled_at.reject! { |_, t| now - t > COOLDOWN }
+      end
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def next_key(provider, keys)
+          instance.next_key(provider, keys)
+        end
+
+        def mark_bad(provider, key)
+          instance.mark_bad(provider, key)
+        end
+
+        def disabled?(provider, key)
+          instance.disabled?(provider, key)
+        end
+
+        def reset!
+          instance.reset!
+        end
+      end
+    end
+  end
+end

data/lib/coordconver/geo/tencent.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Coordconver
+  module Geo
+    # 腾讯位置服务 WebService API
+    # 申请 key: https://lbs.qq.com/dev/console/application/mine (启用 WebServiceAPI)
+    # 坐标为 GCJ-02; 逆地理编码 location 参数为 "lat,lng" 顺序
+    module Tencent
+      extend self
+
+      # 视为"key 无效/配额超限"的状态码, 触发自动轮换下一个 key
+      # 110 请求来源未被授权 112 IP未被授权 120 每秒调用量超限 121 日调用量超限 199 key结构错误
+      KEY_ERROR_STATUSES = [110, 112, 120, 121, 199].freeze
+
+      # 地理编码: 结构化地址 -> 坐标 (GCJ-02)
+      # Coordconver::Tencent.geo("北京市海淀区彩和坊路海淀西大街74号")["result"]["location"]
+      # 支持可选参数: region(城市), get_poi, ...
+      def geo(address, options = {})
+        params = { address: address }.merge(options)
+        request("/geocoder/v1/", params)
+      end
+
+      # 逆地理编码: 坐标 (GCJ-02) -> 结构化地址
+      # Coordconver::Tencent.regeo(116.322987, 39.983424)["result"]["address"]
+      def regeo(lng, lat, options = {})
+        params = {
+          location: "#{lat},#{lng}", # 腾讯接口为 lat,lng 顺序
+          get_poi: 0
+        }.merge(options)
+        request("/geocoder/v1/", params)
+      end
+
+      # IP 定位: IP -> 城市 + 坐标 (GCJ-02)
+      def ip(ip = nil)
+        params = {}
+        params[:ip] = ip unless ip.nil? || ip.empty?
+        request("/location/v1/ip", params)
+      end
+
+      # 便捷方法: 地址 -> [lng, lat] (GCJ-02), 解析失败返回 nil
+      def geo_location(address, options = {})
+        loc = geo(address, options).dig("result", "location")
+        loc && [loc["lng"], loc["lat"]]
+      end
+
+      # 便捷方法: 坐标 -> 地址字符串 (GCJ-02), 解析失败返回 nil
+      def regeo_address(lng, lat, options = {})
+        result = regeo(lng, lat, options).dig("result") || {}
+        result.dig("formatted_addresses", "recommend") || result["address"]
+      end
+
+      private
+
+      def request(path, params)
+        Api.call(
+          provider: :tencent,
+          url: base_url + path,
+          params: params,
+          key_param: :key,
+          bad_result: ->(r) { KEY_ERROR_STATUSES.include?(r["status"].to_i) }
+        )
+      end
+
+      def base_url
+        Configuration.settings[:tencent_base_url].sub(%r{/\z}, "")
+      end
+    end
+  end
+end

data/lib/coordconver/projection.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# 高斯-克吕格投影(横轴墨卡托)正反算, 以及 3°/6° 带号与中央经线换算。
+# 适用于 CGCS2000 / 北京54 / 西安80 / WGS-84 椭球, 精度毫米级。
+#
+# 经 Coordconver.extend(Projection) 挂载:
+#   Coordconver.gauss_kruger(121.47, 31.24)                      # => [x东坐标, y北坐标]
+#   Coordconver.inverse_gauss_kruger(543_000, 3_456_000, central_meridian: 120)
+#   Coordconver.zone_meridian(121.47, width: 3)                  # => [40, 120]
+module Coordconver
+  module Projection
+    extend self
+
+    # 椭球参数: a 长半轴(米), rf 扁率倒数
+    ELLIPSOIDS = {
+      cgcs2000: [6_378_137.0, 298.257_222_101],
+      wgs84: [6_378_137.0, 298.257_223_563],
+      krassovsky: [6_378_245.0, 298.3],       # 北京54
+      iag75: [6_378_140.0, 298.257]           # 西安80
+    }.freeze
+
+    # 高斯-克吕格正算: 经纬度 -> 平面坐标 [东坐标 x, 北坐标 y] (米)
+    # central_meridian: 中央经线(度), 缺省按 zone_width 自动推算
+    # zone_width: 3 或 6 (度), 仅在未指定 central_meridian 时使用
+    # false_easting: 东坐标偏移(米), 默认 500_000 (测绘惯例, 保证 x 为正)
+    # ellipsoid: :cgcs2000 / :wgs84 / :krassovsky(北京54) / :iag75(西安80)
+    def gauss_kruger(lng, lat, central_meridian: nil, zone_width: 6,
+                     ellipsoid: :cgcs2000, false_easting: 500_000, false_northing: 0)
+      a, f = ellipsoid_params(ellipsoid)
+      cm = central_meridian || zone_meridian(lng, width: zone_width)[1]
+      e2 = f * (2 - f)
+      ep2 = e2 / (1 - e2)
+
+      p = deg2rad(lat)
+      dl = deg2rad(lng - cm)
+      sin_p = Math.sin(p)
+      cos_p = Math.cos(p)
+      tan_p = Math.tan(p)
+
+      n = a / Math.sqrt(1 - e2 * sin_p * sin_p)
+      t = tan_p * tan_p
+      c = ep2 * cos_p * cos_p
+      aa = dl * cos_p
+      m = meridional_arc(p, a, e2)
+
+      x = false_easting + n * (aa +
+            (1 - t + c) * aa**3 / 6 +
+            (5 - 18 * t + t * t + 72 * c - 58 * ep2) * aa**5 / 120)
+      y = false_northing + m + n * tan_p * (aa**2 / 2 +
+            (5 - t + 9 * c + 4 * c * c) * aa**4 / 24 +
+            (61 - 58 * t + t * t + 600 * c - 330 * ep2) * aa**6 / 720)
+      [x.round(4), y.round(4)]
+    end
+
+    # 高斯-克吕格反算: 平面坐标 -> 经纬度 [lng, lat]
+    # central_meridian 必填(反算无法从 x, y 推出投影带)
+    def inverse_gauss_kruger(x, y, central_meridian:, ellipsoid: :cgcs2000,
+                             false_easting: 500_000, false_northing: 0)
+      a, f = ellipsoid_params(ellipsoid)
+      e2 = f * (2 - f)
+      ep2 = e2 / (1 - e2)
+
+      m = y - false_northing
+      mu = m / (a * (1 - e2 / 4 - 3 * e2**2 / 64 - 5 * e2**3 / 256))
+      e1 = (1 - Math.sqrt(1 - e2)) / (1 + Math.sqrt(1 - e2))
+
+      p1 = footpoint_latitude(mu, e1)
+      sin_p1 = Math.sin(p1)
+      cos_p1 = Math.cos(p1)
+      tan_p1 = Math.tan(p1)
+
+      c1 = ep2 * cos_p1 * cos_p1
+      t1 = tan_p1 * tan_p1
+      n1 = a / Math.sqrt(1 - e2 * sin_p1 * sin_p1)
+      r1 = a * (1 - e2) / (1 - e2 * sin_p1 * sin_p1)**1.5
+      d = (x - false_easting) / n1
+
+      p = p1 - (n1 * tan_p1 / r1) * (d**2 / 2 -
+            (5 + 3 * t1 + 10 * c1 - 4 * c1 * c1 - 9 * ep2) * d**4 / 24 +
+            (61 + 90 * t1 + 298 * c1 + 45 * t1 * t1 - 252 * ep2 - 3 * c1 * c1) * d**6 / 720)
+      l = (d -
+            (1 + 2 * t1 + c1) * d**3 / 6 +
+            (5 - 2 * c1 + 28 * t1 - 3 * c1 * c1 + 8 * ep2 + 24 * t1 * t1) * d**5 / 120) / cos_p1
+
+      [rad2deg(l + deg2rad(central_meridian)), rad2deg(p)].map { |v| v.round(9) }
+    end
+
+    # 带号与中央经线: zone_meridian(121.47) => [21, 123], zone_meridian(121.47, width: 3) => [40, 120]
+    def zone_meridian(lng, width: 6)
+      raise ArgumentError, "带宽仅支持 3 或 6 度" unless [3, 6].include?(width)
+
+      zone = width == 6 ? (lng / 6).floor + 1 : (lng / 3).round
+      [zone, width == 6 ? zone * 6 - 3 : zone * 3]
+    end
+
+    private
+
+    def ellipsoid_params(name)
+      params = ELLIPSOIDS[name.to_s.downcase.to_sym]
+      raise ArgumentError, "未知椭球: #{name.inspect} (支持 #{ELLIPSOIDS.keys.join(', ')})" unless params
+
+      [params[0], 1.0 / params[1]]
+    end
+
+    # 子午线弧长
+    def meridional_arc(p, a, e2)
+      a * ((1 - e2 / 4 - 3 * e2**2 / 64 - 5 * e2**3 / 256) * p -
+        (3 * e2 / 8 + 3 * e2**2 / 32 + 45 * e2**3 / 1024) * Math.sin(2 * p) +
+        (15 * e2**2 / 256 + 45 * e2**3 / 1024) * Math.sin(4 * p) -
+        (35 * e2**3 / 3072) * Math.sin(6 * p))
+    end
+
+    # 底点纬度迭代
+    def footpoint_latitude(mu, e1)
+      mu + (3 * e1 / 2 - 27 * e1**3 / 32) * Math.sin(2 * mu) +
+        (21 * e1**2 / 16 - 55 * e1**4 / 32) * Math.sin(4 * mu) +
+        (151 * e1**3 / 96) * Math.sin(6 * mu) +
+        (1097 * e1**4 / 512) * Math.sin(8 * mu)
+    end
+
+    def deg2rad(deg)
+      deg * Math::PI / 180.0
+    end
+
+    def rad2deg(rad)
+      rad * 180.0 / Math::PI
+    end
+  end
+end

data/lib/coordconver/utils/http.rb

@@ -1,70 +1,97 @@
-require 'net/http'
-require 'json'
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
 
 module Coordconver
   module Utils
+    # 轻量 HTTP 客户端, 仅依赖标准库。
+    # 网络层失败(超时/连接错误/非 2xx)会自动重试, 重试耗尽后抛出 Coordconver::NetworkError。
     class Http
-
-      DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
-      DEFAULT_OPEN_TIMEOUT = 20
-      DEFAULT_READ_TIMEOUT = 120
+      DEFAULT_OPEN_TIMEOUT = 5
+      DEFAULT_READ_TIMEOUT = 10
       DEFAULT_RETRY_TIMES = 3
-      RETRY_SLEEP_TIME = 3
+      RETRY_BASE_SLEEP = 0.5
 
       HTTP_VERB_MAP = {
-        get:    Net::HTTP::Get,
-        post:   Net::HTTP::Post,
-        put:    Net::HTTP::Put,
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
         delete: Net::HTTP::Delete
-      }
+      }.freeze
 
       DEFAULT_HEADERS = {
-        'user-agent' => DEFAULT_USER_AGENT,
-        'accept' => 'application/json',
-        'content-type' => 'application/json',
-        'connection' => 'close'
-      }
-
-      def initialize(method, url, params: nil, body: nil, headers: {}, opts: {})
-        method = method.downcase.to_sym
-        err_msg = "http method #{method} is not supported"
-        raise err_msg unless HTTP_VERB_MAP.keys.include?(method)
+        "user-agent" => "coordconver/#{Coordconver::VERSION} (+https://github.com/cheenwe/coordconver)",
+        "accept" => "application/json"
+      }.freeze
+
+      RETRYABLE_ERRORS = [
+        Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+        Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, EOFError
+      ].freeze
+
+      def initialize(method, url, params: nil, body: nil, headers: {})
+        method = method.to_s.downcase.to_sym
+        raise ArgumentError, "不支持的 HTTP method: #{method}" unless HTTP_VERB_MAP.key?(method)
+
         @uri = URI(url)
-        @uri.query = URI.encode_www_form(params) unless params.nil?
-        @request = prepare_request(method, body, headers)
-        @opts = opts
+        @uri.query = build_query(params) if params && !params.empty?
+        @method = method
+        @body = body
+        @headers = headers
       end
 
       def send_request
-        tries ||= DEFAULT_RETRY_TIMES
-        opts ||= default_opts.merge @opts
-        Net::HTTP.start(@uri.host, @uri.port, opts) do |http|
-          http.request(@request)
+        attempts = 0
+        begin
+          attempts += 1
+          perform
+        rescue *RETRYABLE_ERRORS => e
+          raise NetworkError, "#{@uri.host} 请求失败: #{e.class}: #{e.message}" if attempts >= DEFAULT_RETRY_TIMES
+
+          sleep(RETRY_BASE_SLEEP * (2**(attempts - 1)))
+          retry
         end
-      # if raise Timeout::Error retry it for 3 times
-      rescue Net::OpenTimeout, Net::ReadTimeout
-        (tries -= 1).zero? ? (raise "Time out") : retry
       end
 
       private
 
-        def prepare_request(method, body, headers)
-          headers = DEFAULT_HEADERS.merge(headers)
-          request = HTTP_VERB_MAP[method].new @uri
-          request.initialize_http_header(headers)
-          request.body = body.to_json unless body.nil?
-          request
+      def perform
+        opts = {
+          use_ssl: @uri.scheme == "https",
+          open_timeout: open_timeout,
+          read_timeout: read_timeout
+        }
+        Net::HTTP.start(@uri.host, @uri.port, **opts) do |http|
+          response = http.request(build_request)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise NetworkError, "#{@uri.host} 返回 HTTP #{response.code}"
+          end
+
+          response
         end
+      end
 
+      def build_request
+        request = HTTP_VERB_MAP[@method].new(@uri)
+        request.initialize_http_header(DEFAULT_HEADERS.merge(@headers))
+        request.body = @body.to_json if @body
+        request
+      end
 
-        def default_opts
-          {
-            use_ssl: 'https' == @uri.scheme,
-            open_timeout: DEFAULT_OPEN_TIMEOUT,
-            read_timeout: DEFAULT_READ_TIMEOUT
-          }
-        end
+      def build_query(params)
+        URI.encode_www_form(params)
+      end
 
+      def open_timeout
+        configured = Coordconver::Geo::Configuration.configured? && Coordconver::Geo::Configuration.settings[:open_timeout]
+        configured || DEFAULT_OPEN_TIMEOUT
+      end
+
+      def read_timeout
+        configured = Coordconver::Geo::Configuration.configured? && Coordconver::Geo::Configuration.settings[:read_timeout]
+        configured || DEFAULT_READ_TIMEOUT
+      end
     end
   end
 end

data/lib/coordconver/utils/request.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Coordconver
   module Utils
     module Request
@@ -7,11 +9,11 @@ module Coordconver
         send_request(:get, url, params: params, headers: headers)
       end
 
-      def post(url, body: , headers: {})
+      def post(url, body: nil, headers: {})
         send_request(:post, url, body: body, headers: headers)
       end
 
-      def put(url, body: , headers: {})
+      def put(url, body: nil, headers: {})
         send_request(:put, url, body: body, headers: headers)
       end
 
@@ -19,17 +21,18 @@ module Coordconver
         send_request(:delete, url, params: params, headers: headers)
       end
 
-      def send_request(method, url, params: nil, body: nil, headers: {}, opts: {})
-        raw_response = Utils::Http.new(
+      def send_request(method, url, params: nil, body: nil, headers: {})
+        raw_response = Http.new(
           method.to_sym,
           url,
           params: params,
           body: body,
-          headers: headers,
-          opts: opts
+          headers: headers
         ).send_request
 
         parse_body(raw_response.body)
+      rescue JSON::ParserError => e
+        raise NetworkError, "响应不是合法 JSON: #{e.message}"
       end
 
       def parse_body(body)

data/lib/coordconver/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Coordconver
-  VERSION = "0.1.4"
+  VERSION = "1.1.0"
 end

data/lib/coordconver.rb

@@ -1,19 +1,33 @@
+# frozen_string_literal: true
+
 require "coordconver/version"
+require "coordconver/errors"
 require "coordconver/coordconver"
 require "coordconver/degree"
+require "coordconver/formats"
+require "coordconver/projection"
 require "coordconver/geo/configuration"
+require "coordconver/geo/key_pool"
+require "coordconver/geo/cache"
+require "coordconver/geo/api"
 require "coordconver/geo/client"
 require "coordconver/geo/baidu"
 require "coordconver/geo/gaode"
+require "coordconver/geo/tencent"
 require "coordconver/utils/http"
 require "coordconver/utils/request"
 
 module Coordconver
+  # 坐标系转换/距离/方位角等方法已直接定义在 Coordconver 单例上,
+  # 如 Coordconver.wgs_gcj(lng, lat) / Coordconver.distance(...) / Coordconver.bearing(...)
+  extend Degree
+  extend Formats
+  extend Projection
 
-  include Coordconver
-  include Degree
-  include Geo::Configuration
-  include Geo
-  include Utils
-
+  # 便捷常量别名, 兼容 Coordconver::Baidu / Coordconver::Gaode 等用法
+  Baidu = Geo::Baidu
+  Gaode = Geo::Gaode
+  Tencent = Geo::Tencent
+  Client = Geo::Client
+  Configuration = Geo::Configuration
 end