kami_backend/.qoder/repowiki/zh/content/API端点参考/风控限制API/风控限制API.md

风控限制API

**本文档中引用的文件** - [province.go](file://api/restriction/v1/province.go) - [collection.go](file://api/restriction/v1/collection.go) - [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go) - [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go) - [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go) - [restriction_v1_block_order.go](file://internal/controller/restriction/restriction_v1_block_order.go) - [restriction.go](file://internal/logic/restriction/restriction.go) - [ip_record.go](file://internal/logic/restriction/ip_record.go) - [location.go](file://utility/integration/restriction/location.go) - [consts.go](file://utility/integration/restriction/consts.go) - [impl.go](file://utility/integration/restriction/impl.go)

目录

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

简介

本文档详细描述了风控限制API的功能实现，涵盖IP限制、地域限制和用户信息收集等核心功能。系统通过多级风控策略实现对用户访问行为的精细化控制，包括基于IP地理位置的访问控制、设备识别与限制、卡密关联限制等功能。API设计遵循RESTful规范，提供清晰的端点定义和安全的数据交互机制。

项目结构

风控限制功能主要分布在API层、控制器层、服务逻辑层和集成工具层，形成清晰的分层架构。各层职责分明，确保功能的可维护性和可扩展性。

graph TB
subgraph "API层"
A[province.go]
B[collection.go]
end
subgraph "控制器层"
C[restriction_v1_check_ip_allowed.go]
D[restriction_v1_query_all_province.go]
E[restriction_v1_user_info_collection.go]
F[restriction_v1_block_order.go]
end
subgraph "服务逻辑层"
G[restriction.go]
H[ip_record.go]
end
subgraph "集成工具层"
I[location.go]
J[consts.go]
K[impl.go]
end
A --> C
B --> E
B --> F
C --> G
D --> G
E --> G
F --> G
G --> H
G --> I
I --> J
I --> K

图示来源

• province.go
• collection.go
• restriction_v1_check_ip_allowed.go
• restriction_v1_query_all_province.go
• restriction_v1_user_info_collection.go
• restriction_v1_block_order.go
• restriction.go
• ip_record.go
• location.go
• consts.go
• impl.go

本节来源

• api/restriction/v1
• internal/controller/restriction

核心组件

风控限制系统的核心组件包括IP地理位置查询、地域限制检查、用户信息收集和订单封禁功能。系统通过集成多个第三方IP定位服务实现高可用的地理位置识别，并结合商户部署策略进行访问控制决策。所有限制记录持久化存储于数据库，支持后续审计和分析。

本节来源

• restriction.go
• location.go

架构概述

系统采用分层架构设计，从API接口到服务逻辑再到外部集成，形成完整的风控处理链路。API层定义清晰的端点契约，控制器层处理请求调度，服务层实现核心业务逻辑，集成层提供外部服务访问能力。

graph TD
Client[客户端] --> API[API接口]
API --> Controller[控制器]
Controller --> Service[服务逻辑]
Service --> Cache[(缓存)]
Service --> Database[(数据库)]
Service --> External[第三方服务]
External --> CSDN[CSDN]
External --> PCOnline[PCOnline]
External --> IP66[IP66]
External --> MeiTu[美图]

图示来源

• restriction.go
• location.go
• impl.go

详细组件分析

IP访问控制分析

系统通过多源IP地理位置服务实现高可用的IP定位功能，采用重试机制确保查询成功率。当主要服务失败时，自动切换到备用服务，保证系统稳定性。

类图

classDiagram
class Location {
<<interface>>
+QueryLocationByIP(ctx, ip) Response, error
}
class CSDNClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class PcOnlineClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class OlToolsClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IdCdClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class MeiTuClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class VoClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class DBIPClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class QJQQClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IQIYIClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IP66Client {
+QueryLocationByIP(ctx, ip) Response, error
}
Location <|-- CSDNClient
Location <|-- PcOnlineClient
Location <|-- OlToolsClient
Location <|-- IdCdClient
Location <|-- MeiTuClient
Location <|-- VoClient
Location <|-- DBIPClient
Location <|-- QJQQClient
Location <|-- IQIYIClient
Location <|-- IP66Client

图示来源

• location.go
• impl.go

省份查询分析

提供获取全国所有省份列表的API接口，支持前端下拉选择等场景。系统维护完整的省份列表，包括特殊行政区和海外地区。

序列图

sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
Client->>API : GET /restriction/location/getAllProvince
API->>Controller : 调用QueryAllProvince
Controller->>Service : 调用GetAllProvince
Service-->>Controller : 返回省份列表
Controller-->>API : 返回响应
API-->>Client : 返回省份列表

图示来源

• province.go
• restriction_v1_query_all_province.go
• restriction.go

用户信息收集分析

实现用户设备信息收集功能，通过加密数据传输确保信息安全。系统验证数据签名防止篡改，并记录设备指纹用于后续风控决策。

流程图

flowchart TD
Start([开始]) --> Decrypt["解密请求数据"]
Decrypt --> Validate["验证数据签名"]
Validate --> SignatureValid{"签名有效?"}
SignatureValid --> |否| ReturnError["返回签名错误"]
SignatureValid --> |是| GetRemoteIP["获取客户端IP"]
GetRemoteIP --> CheckProxy["检查是否使用代理"]
CheckProxy --> SaveDevice["保存设备信息"]
SaveDevice --> End([结束])
ReturnError --> End

图示来源

• collection.go
• restriction_v1_user_info_collection.go
• restriction.go

本节来源

• collection.go
• restriction_v1_user_info_collection.go

依赖分析

系统依赖多个外部IP定位服务和内部服务组件，形成复杂的依赖网络。通过接口抽象降低耦合度，支持服务的灵活替换和扩展。

graph TD
RestrictionService --> IPRecordService
RestrictionService --> MerchantDeployInfoService
RestrictionService --> OrderSummaryService
RestrictionService --> Database
RestrictionService --> CSDNService
RestrictionService --> PCOnlineService
RestrictionService --> IP66Service
RestrictionService --> MeiTuService

图示来源

• restriction.go
• location.go
• consts.go

本节来源

• restriction.go
• location.go

性能考虑

系统通过缓存IP地理位置信息减少外部服务调用，提高响应速度。采用并发处理和重试机制平衡性能与可靠性，确保在高并发场景下的稳定运行。

故障排除指南

常见问题包括IP定位服务不可用、数据签名验证失败和数据库连接异常。建议检查网络连接、服务配置和密钥设置，确保各组件正常运行。

本节来源

• restriction_v1_check_ip_allowed.go
• restriction_v1_user_info_collection.go
• impl.go

结论

风控限制API提供了完整的访问控制解决方案，通过多维度限制策略保障系统安全。系统设计考虑了高可用性、安全性和可扩展性，能够满足复杂的业务场景需求。