# 地域限制API

<cite>
**本文档引用文件**  
- [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)
</cite>

## 目录
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`包中。

```mermaid
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
```

**图示来源**  
- [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/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/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)

**本节来源**  
- [api/restriction/v1/province.go](file://api/restriction/v1/province.go)
- [internal/controller/restriction/restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go)

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

**本节来源**  
- [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_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)

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

```mermaid
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.go](file://internal/controller/restriction/restriction_v1_query_all_province.go)
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

## 详细组件分析

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

#### 对象导向组件：
```mermaid
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~ : "泛型继承"
```

**图示来源**  
- [province.go](file://api/restriction/v1/province.go)

#### API服务组件：
```mermaid
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响应
```

**图示来源**  
- [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

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

#### 复杂逻辑组件：
```mermaid
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
```

**图示来源**  
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

**本节来源**  
- [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_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

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

```mermaid
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
```

**图示来源**  
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [impl.go](file://utility/integration/restriction/impl.go)
- [cache.go](file://utility/cache/cache.go)

**本节来源**  
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [impl.go](file://utility/integration/restriction/impl.go)
- [cache.go](file://utility/cache/cache.go)

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

**本节来源**  
- [cache.go](file://utility/cache/cache.go)
- [location.go](file://utility/integration/restriction/location.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

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

**本节来源**  
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [impl.go](file://utility/integration/restriction/impl.go)

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