danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/API端点参考/风控限制API/地域限制API.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

12 KiB
Raw Blame History

地域限制API

**本文档引用文件** - [province.go](file://api/restriction/v1/province.go) - [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go) - [restriction.go](file://internal/logic/restriction/restriction.go) - [restriction.go](file://internal/service/restriction.go) - [restriction.go](file://internal/model/restriction.go) - [impl.go](file://utility/integration/restriction/impl.go) - [models.go](file://utility/integration/restriction/models.go) - [location.go](file://utility/integration/restriction/location.go) - [cache.go](file://utility/cache/cache.go) - [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go) - [restriction.go](file://internal/consts/restriction.go)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概述
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

本文档详细介绍了地域限制API的功能实现，重点涵盖省份查询和地域控制机制。文档深入解析了restriction_v1_query_all_province端点的实现细节，包括HTTP方法、请求响应模式和数据格式。同时说明了如何通过省份信息实施地域限制策略，并提供了获取所有支持省份列表的使用示例。文档还涵盖了地域数据模型、查询性能优化（如缓存机制）、与IP地理位置服务的集成方式，以及该功能在订单拦截和访问控制中的应用场景。

项目结构

地域限制功能主要分布在API层、控制器层、服务层和集成层。API定义位于api/restriction/v1目录，控制器实现位于internal/controller/restriction目录，核心业务逻辑在internal/logic/restriction包中，IP地理位置查询集成在utility/integration/restriction包中。

graph TD
subgraph "API层"
A[province.go]
B[restriction.go]
end
subgraph "控制器层"
C[restriction_v1_query_all_province.go]
D[restriction_v1_check_ip_allowed.go]
end
subgraph "服务层"
E[restriction.go]
end
subgraph "逻辑层"
F[restriction.go]
end
subgraph "模型层"
G[restriction.go]
end
subgraph "集成层"
H[impl.go]
I[models.go]
J[location.go]
end
A --> C
B --> C
C --> E
E --> F
F --> G
H --> F
I --> H
J --> H

图示来源

本节来源

核心组件

地域限制API的核心组件包括省份查询接口、IP地域检查服务、IP地理位置集成和限制策略执行。QueryAllProvince端点提供获取所有支持省份列表的功能，CheckIPAllowed端点实现基于省份的访问控制。系统通过集成多个IP地理位置服务提供商来确保查询的准确性和可靠性，并利用缓存机制优化查询性能。

本节来源

架构概述

地域限制系统采用分层架构设计，从API接口到数据访问层清晰分离。系统通过RESTful API接收请求，由控制器处理并调用服务层，服务层协调业务逻辑层和数据访问层完成具体操作。IP地理位置查询通过适配器模式集成多个第三方服务，确保高可用性和容错能力。

graph TB
subgraph "客户端"
Client[客户端应用]
end
subgraph "API网关"
API[RESTful API]
end
subgraph "业务逻辑"
Controller[控制器层]
Service[服务层]
Logic[业务逻辑层]
end
subgraph "外部集成"
IPGeo[IP地理位置服务]
Cache[缓存系统]
Database[数据库]
end
Client --> API
API --> Controller
Controller --> Service
Service --> Logic
Logic --> IPGeo
Logic --> Cache
Logic --> Database
Cache --> Logic
Database --> Logic

图示来源

详细组件分析

省份查询组件分析

省份查询功能通过restriction_v1_query_all_province端点实现，提供获取所有支持省份列表的服务。该功能在地域限制策略中作为基础数据支持，用于定义允许或禁止访问的地理区域。

对象导向组件：

classDiagram
class QueryAllProvinceReq {
+string path "/restriction/location/getAllProvince"
+string tags "限制"
+string method "get"
+string summary "获取所有的地理位置"
}
class QueryAllProvinceRes {
+CommonDataRes~string~ CommonDataRes
}
class CommonDataRes~T~ {
+int code
+string message
+T data
}
QueryAllProvinceReq --> QueryAllProvinceRes : "返回"
QueryAllProvinceRes --> CommonDataRes~string~ : "泛型继承"

图示来源

API服务组件：

sequenceDiagram
participant Client as "客户端"
participant Controller as "ControllerV1"
participant Service as "Restriction服务"
participant Logic as "sRestriction逻辑"
Client->>Controller : GET /restriction/location/getAllProvince
Controller->>Service : QueryAllProvince(ctx, req)
Service->>Logic : GetAllProvince(ctx)
Logic-->>Service : 返回省份列表
Service-->>Controller : 构造响应
Controller-->>Client : 返回JSON响应

图示来源

地域控制组件分析

地域控制功能通过CheckIPAllowed端点实现，用于检查特定IP地址是否被允许访问。该功能结合商户部署策略和IP地理位置信息，决定是否允许请求通过。

复杂逻辑组件：

flowchart TD
Start([开始]) --> GetStrategy["获取商户部署策略"]
GetStrategy --> CheckCardPass{"卡密限制启用?"}
CheckCardPass --> |是| CheckCardRestrict["检查卡密限制记录"]
CheckCardRestrict --> IsCardRestricted{"存在限制记录?"}
IsCardRestricted --> |是| ReturnFalse["返回不允许"]
CheckCardPass --> |否| CheckDevice{"设备限制启用?"}
CheckDevice --> |是| CheckDeviceRestrict["检查设备限制"]
CheckDeviceRestrict --> IsDeviceRestricted{"设备被限制?"}
IsDeviceRestricted --> |是| ReturnFalse
CheckDevice --> |否| CheckProxy{"代理限制启用?"}
CheckProxy --> |是| CheckProxyUsage["检查是否使用代理"]
CheckProxyUsage --> IsUsingProxy{"使用代理?"}
IsUsingProxy --> |是| ReturnFalse
CheckProxy --> |否| CheckIP{"IP限制启用?"}
CheckIP --> |是| CheckIPRestrict["检查IP限制记录"]
CheckIPRestrict --> IsIPRestricted{"IP被限制?"}
IsIPRestricted --> |是| ReturnFalse
CheckIP --> |否| CheckInternalIP{"内网IP?"}
CheckInternalIP --> |是| CheckInternalSetting{"限制内网IP?"}
CheckInternalSetting --> |否| ReturnTrue["返回允许"]
CheckInternalIP --> |否| CheckArea{"有地域限制?"}
CheckArea --> |是| CheckProvince["检查IP所在省份"]
CheckProvince --> IsInRestrictedArea{"在限制区域?"}
IsInRestrictedArea --> |是| ReturnFalse
CheckArea --> |否| ReturnTrue
ReturnFalse --> End([结束])
ReturnTrue --> End

图示来源

本节来源

依赖分析

地域限制系统依赖多个内部和外部组件。内部依赖包括服务注册机制、数据库访问、错误处理和配置管理。外部依赖主要为多个IP地理位置查询服务提供商，系统通过集成多个服务商确保查询的可靠性和容错能力。

graph TD
RestrictionAPI --> ServiceLayer
ServiceLayer --> LogicLayer
LogicLayer --> Database
LogicLayer --> Cache
LogicLayer --> IPGeoServices
IPGeoServices --> CSDN
IPGeoServices --> PCOnline
IPGeoServices --> OlTools
IPGeoServices --> IdCd
IPGeoServices --> MeiTu
IPGeoServices --> Vo
IPGeoServices --> DBIP
IPGeoServices --> QJQQ
IPGeoServices --> IQIYI
IPGeoServices --> IP66
Cache --> Redis
Database --> MySQL

图示来源

本节来源

性能考虑

地域限制系统的性能优化主要体现在缓存机制和IP地理位置查询的容错设计上。系统通过Redis缓存频繁访问的数据，减少数据库查询压力。IP地理位置查询采用随机选择和重试机制，确保在某个服务不可用时能够自动切换到其他服务，提高系统的可用性和响应速度。

本节来源

故障排除指南

在使用地域限制API时可能遇到的常见问题包括IP地理位置查询失败、缓存不一致和策略配置错误。建议首先检查网络连接是否正常，确认第三方IP地理位置服务是否可用。对于缓存问题，可以尝试清除相关缓存键。策略配置问题需要检查商户部署配置中的限制设置是否正确。

本节来源

结论

地域限制API提供了一套完整的地理位置控制解决方案，通过省份查询和IP检查功能实现了灵活的访问控制策略。系统设计考虑了高可用性和性能优化，通过集成多个IP地理位置服务提供商和使用缓存机制，确保了服务的稳定性和响应速度。该功能在订单拦截和访问控制场景中具有重要应用价值。