f9f3dec53f
- 注释掉Podfile中的Alamofire依赖，更新Podfile.lock以反映更改。 - 在yana/APIs/API-README.md中新增自动认证Header机制的详细文档，描述其工作原理、实现细节及最佳实践。 - 在yana/yanaApp.swift中将print语句替换为debugInfo以增强调试信息的输出。 - 在API相关文件中实现用户认证状态检查和相关header的自动添加逻辑，提升API请求的安全性和用户体验。 - 更新多个文件中的日志输出，确保在DEBUG模式下提供详细的调试信息。
152 lines
3.9 KiB
Markdown
152 lines
3.9 KiB
Markdown
## 🔐 **自动认证 Header 机制**
|
||
|
||
### 概述
|
||
|
||
系统会自动检查用户的登录状态，并在所有API请求中自动添加认证相关的header。
|
||
|
||
### 工作原理
|
||
|
||
1. **检查认证状态**：每次发起API请求时，系统会检查`AccountModel`的有效性
|
||
2. **自动添加Header**：如果用户已登录且认证信息有效，自动添加以下header：
|
||
- `pub_uid`: 用户唯一标识（来自`AccountModel.uid`）
|
||
- `pub_ticket`: 业务会话票据（来自`AccountModel.ticket`）
|
||
|
||
### 实现细节
|
||
|
||
```swift
|
||
// 在 APIConfiguration.defaultHeaders 中实现
|
||
static var defaultHeaders: [String: String] {
|
||
var headers = [
|
||
"Content-Type": "application/json",
|
||
"Accept": "application/json",
|
||
// ... 其他基础header
|
||
]
|
||
|
||
// 检查用户认证状态并添加相关 headers
|
||
let authStatus = UserInfoManager.checkAuthenticationStatus()
|
||
|
||
if authStatus.canAutoLogin {
|
||
// 添加认证 headers（仅在 AccountModel 有效时）
|
||
if let userId = UserInfoManager.getCurrentUserId() {
|
||
headers["pub_uid"] = userId
|
||
}
|
||
|
||
if let userTicket = UserInfoManager.getCurrentUserTicket() {
|
||
headers["pub_ticket"] = userTicket
|
||
}
|
||
}
|
||
|
||
return headers
|
||
}
|
||
```
|
||
|
||
### 认证状态检查
|
||
|
||
系统使用`UserInfoManager.checkAuthenticationStatus()`检查认证状态：
|
||
|
||
```swift
|
||
enum AuthenticationStatus {
|
||
case valid // 认证有效，可以自动登录
|
||
case invalid // 认证信息不完整或无效
|
||
case notFound // 未找到认证信息
|
||
}
|
||
```
|
||
|
||
**认证有效的条件**：
|
||
- `AccountModel`存在
|
||
- `uid`不为空
|
||
- `ticket`不为空
|
||
- `accessToken`不为空
|
||
|
||
### 使用方式
|
||
|
||
认证header的添加是**完全自动的**，开发者无需手动处理：
|
||
|
||
```swift
|
||
// 示例：发起API请求
|
||
let request = ConfigRequest()
|
||
let response = try await apiService.request(request)
|
||
|
||
// 如果用户已登录，以上请求会自动包含：
|
||
// Header: pub_uid = "12345"
|
||
// Header: pub_ticket = "eyJhbGciOiJIUzI1NiJ9..."
|
||
```
|
||
|
||
### 测试功能
|
||
|
||
在DEBUG模式下，可以使用测试方法验证功能：
|
||
|
||
```swift
|
||
#if DEBUG
|
||
// 运行认证header测试
|
||
UserInfoManager.testAuthenticationHeaders()
|
||
#endif
|
||
```
|
||
|
||
测试包括：
|
||
1. **未登录状态测试**：验证不会添加认证header
|
||
2. **已登录状态测试**：验证正确添加认证header
|
||
3. **清理测试**：验证测试数据正确清理
|
||
|
||
### 调试日志
|
||
|
||
在DEBUG模式下，系统会输出认证header的添加情况：
|
||
|
||
```
|
||
🔐 添加认证 header: pub_uid = 12345
|
||
🔐 添加认证 header: pub_ticket = eyJhbGciOiJIUzI1NiJ9...
|
||
```
|
||
|
||
或者：
|
||
|
||
```
|
||
🔐 跳过认证 header 添加 - 认证状态: 未找到认证信息
|
||
```
|
||
|
||
### 最佳实践
|
||
|
||
1. **登录成功后保存完整认证信息**：
|
||
```swift
|
||
UserInfoManager.saveCompleteAuthenticationData(
|
||
accessToken: loginResponse.accessToken,
|
||
ticket: ticketResponse.ticket,
|
||
uid: loginResponse.uid,
|
||
userInfo: loginResponse.userInfo
|
||
)
|
||
```
|
||
|
||
2. **登出时清理认证信息**：
|
||
```swift
|
||
UserInfoManager.clearAllAuthenticationData()
|
||
```
|
||
|
||
3. **应用启动时检查认证状态**：
|
||
```swift
|
||
let authStatus = UserInfoManager.checkAuthenticationStatus()
|
||
if authStatus.canAutoLogin {
|
||
// 可以直接进入主界面
|
||
} else {
|
||
// 需要重新登录
|
||
}
|
||
```
|
||
|
||
### 安全考虑
|
||
|
||
- **内存安全**：ticket存储在内存中，应用重启需重新获取
|
||
- **持久化安全**：uid和accessToken存储在Keychain中，确保安全性
|
||
- **自动清理**：认证失效时系统会自动停止添加认证header
|
||
|
||
### 故障排除
|
||
|
||
1. **认证header未添加**：
|
||
- 检查用户是否已正确登录
|
||
- 验证AccountModel是否包含有效的uid和ticket
|
||
- 确认认证状态为valid
|
||
|
||
2. **ticket为空**：
|
||
- 检查登录流程是否正确获取了ticket
|
||
- 验证ticket是否正确保存到AccountModel
|
||
|
||
3. **调试模式下查看详细日志**：
|
||
- 启用DEBUG模式查看认证header添加日志
|
||
- 使用测试方法验证功能正确性 |