huace-aigc-auth-client 1.1.33__tar.gz → 1.1.35__tar.gz

{huace_aigc_auth_client-1.1.33/huace_aigc_auth_client.egg-info → huace_aigc_auth_client-1.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huace-aigc-auth-client
-Version: 1.1.33
+Version: 1.1.35
 Summary: 华策AIGC Auth Client - 提供 Token 验证、用户信息获取、权限检查、旧系统接入等功能
 Author-email: Huace <support@huace.com>
 License: MIT
@@ -691,6 +691,329 @@ sync_config = create_sync_config(
 
 ---
 
+## 高级功能
+
+### API 统计收集
+
+SDK 提供了接口统计收集功能，自动收集和上报 API 调用数据到鉴权中心。
+
+#### 1. 初始化统计收集器
+
+```python
+from huace_aigc_auth_client import init_api_stats_collector
+
+# 仅仅示例，SDK 接入鉴权会默认启用数据收集功能（可以手动传参关闭）
+# 在应用启动时初始化
+init_api_stats_collector(
+    api_url='http://auth.example.com/api/sdk',
+    app_id='your-app-id',
+    app_secret='your-app-secret',
+    batch_size=10,          # 批量提交大小
+    flush_interval=5.0,     # 刷新间隔（秒）
+    enabled=True            # 是否启用
+)
+```
+
+#### 2. 在中间件中自动收集
+
+**FastAPI 示例：**
+
+```python
+from fastapi import FastAPI, Request
+from huace_aigc_auth_client import collect_api_stat
+import time
+
+app = FastAPI()
+
+
+# 仅仅示例，SDK 内默认会启用数据收集未 exclude 的接口（可以手动传参关闭）
+@app.middleware("http") 
+async def monitor_middleware(request: Request, call_next):
+    start_time = time.time()
+    
+    try:
+        response = await call_next(request)
+        response_time = time.time() - start_time
+        
+        # 从请求上下文获取 token
+        token = request.state.user_info.token if hasattr(request.state, 'user_info') else None
+        
+        # 收集统计（会自动过滤 3xx 重定向请求）
+        collect_api_stat(
+            api_path=request.url.path,
+            api_method=request.method,
+            status_code=response.status_code,
+            response_time=response_time,
+            token=token,
+            request_params={
+                'headers': dict(request.headers),
+                'query_params': dict(request.query_params)
+            }
+        )
+        
+        return response
+    except Exception as e:
+        response_time = time.time() - start_time
+        collect_api_stat(
+            api_path=request.url.path,
+            api_method=request.method,
+            status_code=500,
+            response_time=response_time,
+            token=token,
+            error_message=str(e)
+        )
+        raise
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    from huace_aigc_auth_client import stop_api_stats_collector
+    stop_api_stats_collector()
+```
+
+**特性说明：**
+- 异步队列收集，不阻塞主流程
+- 批量提交，减少网络开销
+- 自动过滤 3xx 重定向请求
+- 按 token 分组提交
+- 静默失败，不影响主业务
+
+---
+
+### 认证请求封装
+
+SDK 提供了 `auth_request` 函数，封装标准的 HTTP 请求，自动添加认证信息并上报统计。
+
+#### 1. 基本使用
+
+```python
+from huace_aigc_auth_client import auth_request, set_request_context
+
+# 设置请求上下文（通常在中间件中完成）
+set_request_context(
+    app_id='your-app-id',
+    app_secret='your-app-secret',
+    token='user-access-token',
+    ip_address='192.168.1.1',
+    user_agent='Mozilla/5.0...',
+    trace_id='trace-123'
+)
+
+# 发起请求（会自动添加认证信息）
+response = auth_request('GET', 'https://api.example.com/data')
+print(response.json())
+```
+
+#### 2. 带参数的请求
+
+```python
+# GET 请求带查询参数
+response = auth_request(
+    'GET',
+    'https://api.example.com/users',
+    params={'page': 1, 'size': 10}
+)
+
+# POST 请求带 JSON 数据
+response = auth_request(
+    'POST',
+    'https://api.example.com/users',
+    json={'name': 'John', 'email': 'john@example.com'}
+)
+
+# POST 请求带表单数据
+response = auth_request(
+    'POST',
+    'https://api.example.com/upload',
+    data={'field1': 'value1', 'field2': 'value2'}
+)
+```
+
+#### 3. 异步请求（httpx）
+
+需要安装 httpx：`pip install httpx`
+
+```python
+from huace_aigc_auth_client import async_auth_httpx_request, AsyncAuthClient
+import asyncio
+
+# 方式1：使用函数
+async def example1():
+    response = await async_auth_httpx_request('GET', 'https://api.example.com/data')
+    print(response.json())
+
+# 方式2：使用 AsyncAuthClient（推荐用于多个请求）
+async def example2():
+    async with AsyncAuthClient(timeout=10.0) as client:
+        # POST 请求
+        response = await client.post(
+            'https://api.example.com/users',
+            json={'name': 'John'}
+        )
+        
+        # GET 请求
+        response = await client.get(
+            'https://api.example.com/users',
+            params={'page': 1}
+        )
+
+asyncio.run(example1())
+```
+
+**自动添加的请求头：**
+- `X-App-ID`: 应用ID
+- `X-App-Secret`: 应用密钥
+- `Authorization`: Bearer token
+- `x-real-ip`: 客户端真实IP
+- `user-agent`: User Agent
+- `X-Trace-ID`: 追踪ID
+
+---
+
+### 用户上下文管理
+
+SDK 提供了完整的用户上下文管理功能，支持同步和异步环境。
+
+#### 1. 设置和获取用户信息
+
+```python
+from huace_aigc_auth_client import (
+    set_current_user, 
+    get_current_user,
+    get_current_user_id,
+    get_current_username,
+    is_current_user_admin
+)
+
+# 在中间件中设置
+set_current_user({
+    'user_id': 123,
+    'username': 'john',
+    'app_id': 1,
+    'app_code': 'myapp',
+    'token': 'xxx',
+    'roles': ['admin'],
+    'permissions': ['user:read', 'user:write'],
+    'is_admin': True
+})
+
+# 在业务代码中获取
+def some_business_logic():
+    user = get_current_user()
+    user_id = get_current_user_id()
+    username = get_current_username()
+    
+    if user:
+        print(f"当前用户: {username} ({user_id})")
+        
+    if is_current_user_admin():
+        print("当前用户是管理员")
+```
+
+#### 2. 请求上下文管理
+
+```python
+from huace_aigc_auth_client import (
+    set_request_context,
+    get_request_context,
+    get_client_ip,
+    get_user_agent,
+    get_trace_id
+)
+
+# 设置请求上下文
+set_request_context(
+    ip_address='192.168.1.1',
+    user_agent='Mozilla/5.0...',
+    trace_id='trace-123',
+    app_id='your-app-id',
+    app_secret='your-app-secret',
+    token='user-token'
+)
+
+# 获取请求上下文信息
+ctx = get_request_context()
+ip = get_client_ip()
+ua = get_user_agent()
+trace = get_trace_id()
+```
+
+#### 3. 在 FastAPI 中集成
+
+```python
+from fastapi import FastAPI, Request, Depends
+from huace_aigc_auth_client import (
+    set_current_user,
+    set_request_context,
+    get_current_user,
+    clear_current_user,
+    clear_request_context
+)
+
+app = FastAPI()
+
+@app.middleware("http")
+async def user_context_middleware(request: Request, call_next):
+    # 从认证中获取用户信息
+    user_info = request.state.user_info if hasattr(request.state, 'user_info') else None
+    
+    if user_info:
+        # 设置用户上下文
+        set_current_user({
+            'user_id': user_info.id,
+            'username': user_info.username,
+            'app_id': getattr(user_info, 'app_id', None),
+            'is_admin': user_info.is_admin
+        })
+        
+        # 设置请求上下文
+        set_request_context(
+            ip_address=request.client.host,
+            user_agent=request.headers.get('user-agent'),
+            trace_id=request.headers.get('x-trace-id'),
+            token=request.headers.get('authorization', '').replace('Bearer ', '')
+        )
+    
+    try:
+        response = await call_next(request)
+        return response
+    finally:
+        clear_current_user()
+        clear_request_context()
+
+# 在任意地方使用
+def my_service_function():
+    user = get_current_user()
+    if user:
+        print(f"执行操作的用户: {user['username']}")
+```
+
+#### 4. 装饰器中使用
+
+```python
+from functools import wraps
+from huace_aigc_auth_client import is_current_user_admin
+
+def require_admin(func):
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        if not is_current_user_admin():
+            raise HTTPException(status_code=403, detail="需要管理员权限")
+        return await func(*args, **kwargs)
+    return wrapper
+
+@require_admin
+async def admin_endpoint():
+    return {"message": "管理员操作"}
+```
+
+**特性说明：**
+- 使用 `threading.local()` 和 `contextvars.ContextVar` 实现
+- 同时支持同步和异步环境
+- 线程安全和异步任务隔离
+- 无需层层传递参数
+
+---
+
 ## 导出清单
 
 ```python
@@ -720,6 +1043,36 @@ from huace_aigc_auth_client import (
     # Webhook 接收
     register_webhook_router,
     verify_webhook_signature,
+    
+    # API 统计收集
+    ApiStatsCollector,
+    init_api_stats_collector,
+    get_api_stats_collector,
+    stop_api_stats_collector,
+    collect_api_stat,
+    
+    # 认证请求封装
+    auth_request,
+    async_auth_httpx_request,
+    AsyncAuthClient,
+    
+    # 用户上下文管理
+    set_current_user,
+    get_current_user,
+    get_current_user_id,
+    get_current_username,
+    get_current_app_id,
+    get_current_app_code,
+    is_current_user_admin,
+    clear_current_user,
+    set_request_context,
+    get_request_context,
+    get_client_ip,
+    get_user_agent,
+    get_request_id,
+    get_trace_id,
+    get_request_token,
+    clear_request_context,
 )
 ```