这是基于vue-vben-admin 模板适用于abp vNext的前端管理项目

18 KiB

Raw Blame History

腾讯位置服务集成

**本文档引用的文件** - [TencentLocationOptions.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/TencentLocationOptions.cs) - [TencentLocationHttpClient.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/TencentLocationHttpClient.cs) - [TencentSecretKeyCaculater.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Utils/TencentSecretKeyCaculater.cs) - [TencentLocationResponse.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Response/TencentLocationResponse.cs) - [TencentIPGeocodeResponse.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Response/TencentIPGeocodeResponse.cs) - [TencentGeocodeResponse.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Response/TencentGeocodeResponse.cs) - [TencentReGeocodeResponse.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Response/TencentReGeocodeResponse.cs) - [TencentIPGeocode.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Model/TencentIPGeocode.cs) - [TencentGeocode.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Model/TencentGeocode.cs) - [TencentReGeocode.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/Model/TencentReGeocode.cs) - [AbpTencentLocationModule.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/AbpTencentLocationModule.cs) - [TencentLocationResolveProvider.cs](file://aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent/LINGYUN/Abp/Location/Tencent/TencentLocationResolveProvider.cs) - [appsettings.json](file://aspnet-core/services/LY.MicroService.Applications.Single/appsettings.json)

简介

本文档详细说明了腾讯位置服务SDK的集成方法，包括SecretId和SecretKey的配置、地理编码、逆地理编码、行政区划查询等API调用方式。文档涵盖了HTTPS请求配置、签名算法实现、请求频率限制处理以及服务不可用时的容错机制。同时提供了在微服务架构中调用腾讯位置服务的最佳实践，包括异步调用、超时设置、结果缓存等技术细节，并说明了与腾讯云等其他云服务的协同使用方法。

项目结构

腾讯位置服务集成模块位于aspnet-core/framework/common/LINGYUN.Abp.Location.Tencent目录下，包含配置选项、HTTP客户端、响应模型、工具类等核心组件。该模块通过ABP框架的依赖注入系统进行注册和管理，支持通过配置文件灵活配置各项参数。

graph TD
A[TencentLocationOptions] --> B[TencentLocationHttpClient]
C[TencentSecretKeyCaculater] --> B
D[TencentLocationResponse] --> E[TencentIPGeocodeResponse]
D --> F[TencentGeocodeResponse]
D --> G[TencentReGeocodeResponse]
B --> H[TencentLocationResolveProvider]
I[AbpTencentLocationModule] --> B
I --> J[TencentLocationHttpConsts]

图示来源

TencentLocationOptions.cs
TencentLocationHttpClient.cs
TencentSecretKeyCaculater.cs
TencentLocationResponse.cs
TencentIPGeocodeResponse.cs
TencentGeocodeResponse.cs
TencentReGeocodeResponse.cs
AbpTencentLocationModule.cs
TencentLocationHttpConsts.cs

本节来源

TencentLocationOptions.cs
TencentLocationHttpClient.cs

核心组件

腾讯位置服务集成的核心组件包括配置选项、HTTP客户端、响应模型、签名计算工具和解析提供程序。这些组件共同实现了对腾讯位置服务API的封装和调用。

本节来源

TencentLocationOptions.cs
TencentLocationHttpClient.cs
TencentSecretKeyCaculater.cs

架构概述

腾讯位置服务集成采用分层架构设计，包括配置层、客户端层、响应处理层和业务逻辑层。通过ABP框架的依赖注入和模块化设计，实现了高内聚低耦合的系统结构。

classDiagram
class TencentLocationOptions {
+string AccessKey
+string SecretKey
+string GetPoi
+string Output
+string Callback
+bool VisableErrorToClient
}
class TencentLocationHttpClient {
-TencentLocationOptions Options
-IServiceProvider ServiceProvider
-IHttpClientFactory HttpClientFactory
-ICancellationTokenProvider CancellationTokenProvider
+Task~IPGecodeLocation~ IPGeocodeAsync(string ipAddress)
+Task~GecodeLocation~ GeocodeAsync(string address, string city)
+Task~ReGeocodeLocation~ ReGeocodeAsync(double lat, double lng, int radius)
-Task~string~ MakeRequestAndGetResultAsync(string url)
-CancellationToken GetCancellationToken()
-Task~TResponse~ GetTencentMapResponseAsync~TResponse~(string url, string path, IDictionary~string, string~ paramters)
-string BuildRequestUrl(string uri, string path, IDictionary~string, string~ paramters)
}
class TencentSecretKeyCaculater {
-static string MD5(string password)
-static string HttpBuildQuery(IDictionary~string, string~ querystring_arrays)
+static string CalcSecretKey(string url, string secretKey, IDictionary~string, string~ querystring_arrays)
}
class TencentLocationResponse {
+int Status
+string Message
+string RequestId
+bool IsSuccessed
+ILocalizableString GetErrorMessage(bool throwToClient)
}
class TencentIPGeocodeResponse {
+TencentIPGeocode Result
}
class TencentGeocodeResponse {
+TencentGeocode Result
}
class TencentReGeocodeResponse {
+TencentReGeocode Result
}
class TencentLocationResolveProvider {
-TencentLocationHttpClient TencentLocationHttpClient
+Task~IPGecodeLocation~ IPGeocodeAsync(string ipAddress)
+Task~ReGeocodeLocation~ ReGeocodeAsync(double lat, double lng, int radius)
+Task~GecodeLocation~ GeocodeAsync(string address, string city)
}
class AbpTencentLocationModule {
+void ConfigureServices(ServiceConfigurationContext context)
}
TencentLocationHttpClient --> TencentLocationOptions : "使用"
TencentLocationHttpClient --> TencentSecretKeyCaculater : "使用"
TencentLocationHttpClient --> TencentLocationResponse : "返回"
TencentLocationResolveProvider --> TencentLocationHttpClient : "依赖"
AbpTencentLocationModule --> TencentLocationHttpClient : "注册"
TencentIPGeocodeResponse --|> TencentLocationResponse : "继承"
TencentGeocodeResponse --|> TencentLocationResponse : "继承"
TencentReGeocodeResponse --|> TencentLocationResponse : "继承"

图示来源

TencentLocationOptions.cs
TencentLocationHttpClient.cs
TencentSecretKeyCaculater.cs
TencentLocationResponse.cs
TencentIPGeocodeResponse.cs
TencentGeocodeResponse.cs
TencentReGeocodeResponse.cs
TencentLocationResolveProvider.cs
AbpTencentLocationModule.cs

详细组件分析

配置选项分析

腾讯位置服务的配置选项通过TencentLocationOptions类定义，支持在应用配置文件中进行设置。主要配置项包括：

配置项	描述	默认值
AccessKey	腾讯地图API的访问密钥	无
SecretKey	腾讯地图API的签名密钥	无
GetPoi	是否返回周边POI信息	"1"
Output	返回数据格式	"JSON"
Callback	JSONP回调函数名称	null
VisableErrorToClient	是否将错误信息暴露给客户端	false

本节来源

TencentLocationOptions.cs

HTTP客户端分析

TencentLocationHttpClient是腾讯位置服务的核心客户端类，负责构建请求、处理响应和错误。该类通过依赖注入获取配置选项和HTTP工厂，实现了以下功能：

sequenceDiagram
participant Client as "客户端"
participant Provider as "TencentLocationResolveProvider"
participant HttpClient as "TencentLocationHttpClient"
participant Factory as "HttpClientFactory"
participant Server as "腾讯位置服务"
Client->>Provider : 调用GeocodeAsync
Provider->>HttpClient : 调用GeocodeAsync
HttpClient->>HttpClient : 构建请求参数
HttpClient->>HttpClient : 计算签名如有
HttpClient->>HttpClient : 构建请求URL
HttpClient->>Factory : 创建HttpClient
Factory-->>HttpClient : 返回HttpClient
HttpClient->>Server : 发送GET请求
Server-->>HttpClient : 返回响应
HttpClient->>HttpClient : 解析响应JSON
HttpClient->>HttpClient : 检查状态码
alt 状态码为0
HttpClient-->>Provider : 返回解析结果
Provider-->>Client : 返回地理位置信息
else 状态码非0
HttpClient->>HttpClient : 处理错误
HttpClient--x Client : 抛出异常
end

图示来源

TencentLocationHttpClient.cs
TencentLocationResolveProvider.cs

本节来源

TencentLocationHttpClient.cs

签名算法分析

腾讯位置服务要求对请求进行签名验证，签名算法通过TencentSecretKeyCaculater类实现。签名计算过程如下：

flowchart TD
Start([开始]) --> BuildQuery["构建查询字符串"]
BuildQuery --> Concat["拼接URL+?+查询字符串+SecretKey"]
Concat --> MD5["计算MD5哈希值"]
MD5 --> Return["返回签名结果"]
Return --> End([结束])

具体实现代码：

public static string CalcSecretKey(string url, string secretKey, IDictionary<string, string> querystring_arrays)
{
    var queryString = HttpBuildQuery(querystring_arrays);
    return MD5(url + "?" + queryString + secretKey);
}

图示来源

TencentSecretKeyCaculater.cs

本节来源

TencentSecretKeyCaculater.cs

响应模型分析

腾讯位置服务的响应模型采用继承结构，基础响应类TencentLocationResponse定义了通用的状态码和消息字段，具体响应类型继承自基础响应类。

classDiagram
class TencentLocationResponse {
+int Status
+string Message
+string RequestId
+bool IsSuccessed
+ILocalizableString GetErrorMessage(bool throwToClient)
}
class TencentIPGeocodeResponse {
+TencentIPGeocode Result
}
class TencentGeocodeResponse {
+TencentGeocode Result
}
class TencentReGeocodeResponse {
+TencentReGeocode Result
}
TencentIPGeocodeResponse --|> TencentLocationResponse : "继承"
TencentGeocodeResponse --|> TencentLocationResponse : "继承"
TencentReGeocodeResponse --|> TencentLocationResponse : "继承"

图示来源

TencentLocationResponse.cs
TencentIPGeocodeResponse.cs
TencentGeocodeResponse.cs
TencentReGeocodeResponse.cs

本节来源

TencentLocationResponse.cs

依赖分析

腾讯位置服务集成模块依赖于ABP框架的核心组件，包括依赖注入、配置系统、本地化和虚拟文件系统。同时使用HttpClientFactory进行HTTP请求，通过Polly库实现重试策略。

graph LR
A[AbpTencentLocationModule] --> B[Volo.Abp.Core]
A --> C[Volo.Abp.DependencyInjection]
A --> D[Volo.Abp.Configuration]
A --> E[Volo.Abp.Localization]
A --> F[Volo.Abp.VirtualFileSystem]
A --> G[System.Net.Http]
A --> H[Polly]
A --> I[Newtonsoft.Json]

图示来源

AbpTencentLocationModule.cs

本节来源

AbpTencentLocationModule.cs

性能考虑

腾讯位置服务集成在性能方面做了多项优化：

HTTP客户端重用：通过HttpClientFactory创建命名HttpClient，实现连接池复用
重试策略：使用Polly库实现指数退避重试，最多重试3次
异步调用：所有API调用均为异步方法，避免阻塞线程
缓存建议：建议在业务层实现结果缓存，减少重复请求

重试策略配置：

context.Services.AddHttpClient(TencentLocationHttpConsts.HttpClientName)
   .AddTransientHttpErrorPolicy(builder =>
       builder.WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(Math.Pow(2, i))));

本节来源

AbpTencentLocationModule.cs
TencentLocationHttpClient.cs

故障排除指南

配置问题

确保在appsettings.json中正确配置腾讯位置服务参数：

{
  "Location": {
    "Tencent": {
      "AccessKey": "your-access-key",
      "SecretKey": "your-secret-key",
      "GetPoi": "1",
      "Output": "JSON",
      "VisableErrorToClient": false
    }
  }
}

常见错误码

错误码	描述	解决方案
0	正常	无需处理
310	请求参数信息有误	检查请求参数是否正确
311	Key格式错误	检查AccessKey和SecretKey格式
306	请求有护持信息请检查字符串	检查请求字符串是否有非法字符
110	请求来源未被授权	检查域名白名单配置

签名验证失败

签名验证失败通常由以下原因导致：

SecretKey配置错误
请求参数顺序不一致
URL路径错误
时间戳过期

本节来源

TencentLocationResponse.cs
TencentSecretKeyCaculater.cs
appsettings.json

结论

腾讯位置服务集成模块提供了完整的地理位置服务解决方案，包括地理编码、逆地理编码和IP定位功能。通过合理的架构设计和错误处理机制，确保了服务的稳定性和可靠性。建议在生产环境中启用结果缓存，并合理配置重试策略以应对网络波动。

18 KiB Raw Blame History

腾讯位置服务集成

目录

简介

项目结构

核心组件

架构概述

详细组件分析

配置选项分析

HTTP客户端分析

签名算法分析

响应模型分析

依赖分析

性能考虑

故障排除指南

配置问题

常见错误码

签名验证失败

结论

18 KiB

Raw Blame History