接口概述
为已登录用户提供订单列表的只读分页检索能力。客户端可通过可选的状态过滤、更新时间过滤及分页参数获取订单数据。典型使用场景：
- 订单中心列表页的首次加载与下拉刷新
- 上拉加载更多分页数据
- 按状态筛选（待支付、已支付、已发货、已取消）
- 基于更新时间的增量同步（配合 ETag 与 updated_after）
支持 iOS 端通过 Authorization 认证访问，并支持 ETag 条件请求以减少流量和加快加载。
请求方式
- HTTP 方法：GET
- 路径：/api/v1/orders
- 认证：Authorization: Bearer （必需）
请求头（建议/可选）：
- Accept: application/json
- If-None-Match: （可选，用于条件请求）
请求参数
说明：
- 所有查询参数均可选，若未提供则由服务端采用默认策略（本文档未定义）。
- 参数校验不通过时，服务端可能返回 422。
查询参数：
- status
- 类型：string
- 是否必填：否
- 取值枚举：pending, paid, shipped, canceled
- 说明：按订单状态筛选。
- page
- 类型：int
- 是否必填：否
- 范围：>= 1
- 说明：分页页码。用于获取指定页数据。
- page_size
- 类型：int
- 是否必填：否
- 范围：<= 100
- 说明：每页返回的记录数上限。
- updated_after
- 类型：string
- 是否必填：否
- 格式：RFC3339（例如：2024-01-10T12:00:00Z）
- 说明：仅返回该时间点之后更新的订单，用于增量同步。
响应格式
成功响应（HTTP 200）为 JSON 对象，包含以下字段：
- items：array[object]
- order_id：string
- status：string（枚举：pending, paid, shipped, canceled）
- amount：number（建议在客户端使用 Decimal 处理货币）
- currency：string（ISO-4217 货币代码，如 "USD", "CNY"）
- created_at：string（ISO8601 日期时间，例如：2024-01-10T12:00:00Z）
- meta：object
- total：int（符合当前筛选条件的总记录数）
- page：int（当前页码）
- page_size：int（当前页大小）
- has_next：bool（是否存在下一页）
条件请求（ETag）：
- 响应可能包含响应头：ETag: ""
- 当客户端携带 If-None-Match: "" 且数据未变化时，服务端可返回 304 Not Modified（无响应体）。此状态不属于错误。
错误代码
- 401 Unauthorized：未提供或提供了无效的令牌（Authorization 失败）。
- 403 Forbidden：已认证，但无访问该资源的权限。
- 422 Unprocessable Entity：参数不合法（例如：page < 1、page_size > 100、status 非法、updated_after 格式不符合 RFC3339）。
- 500 Internal Server Error：服务器内部错误。
使用示例
示例请求（带筛选与分页）：
GET /api/v1/orders?status=paid&page=1&page_size=20&updated_after=2024-01-10T12:00:00Z
Accept: application/json
Authorization: Bearer
If-None-Match: "W/"e19d5cd5af0378da05f63f891c7467af""
示例成功响应（200 OK）：
{
"items": [
{
"order_id": "ord_202501011234",
"status": "paid",
"amount": 199.99,
"currency": "USD",
"created_at": "2025-01-02T08:30:15Z"
},
{
"order_id": "ord_202501011235",
"status": "paid",
"amount": 59.50,
"currency": "USD",
"created_at": "2025-01-02T10:12:00Z"
}
],
"meta": {
"total": 142,
"page": 1,
"page_size": 20,
"has_next": true
}
}
示例条件请求未修改（304 Not Modified，无响应体）：
HTTP/1.1 304 Not Modified
iOS 端 Swift 代码示例（URLComponents 构建查询 + ISO8601 解析 + ETag 缓存）：
// 1) 定义模型
struct OrdersResponse: Decodable {
let items: [Order]
let meta: Meta
struct Order: Decodable {
let orderId: String
let status: String
let amount: Decimal
let currency: String
let createdAt: Date
enum CodingKeys: String, CodingKey {
case orderId = "order_id"
case status
case amount
case currency
case createdAt = "created_at"
}
}
struct Meta: Decodable {
let total: Int
let page: Int
let pageSize: Int
let hasNext: Bool
enum CodingKeys: String, CodingKey {
case total, page
case pageSize = "page_size"
case hasNext = "has_next"
}
}
}
// 2) 灵活的 ISO8601 解码（兼容是否带毫秒）
final class ISO8601FlexibleDecoder {
static let withoutFractional: ISO8601DateFormatter = {
let f = ISO8601DateFormatter()
f.formatOptions = [.withInternetDateTime, .withColonSeparatorInTimeZone]
return f
}()
static let withFractional: ISO8601DateFormatter = {
let f = ISO8601DateFormatter()
f.formatOptions = [.withInternetDateTime, .withFractionalSeconds, .withColonSeparatorInTimeZone]
return f
}()
static func decoder() -> JSONDecoder {
let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .useDefaultKeys
decoder.dateDecodingStrategy = .custom { decoder -> Date in
let container = try decoder.singleValueContainer()
let str = try container.decode(String.self)
if let d = withFractional.date(from: str) ?? withoutFractional.date(from: str) {
return d
}
throw DecodingError.dataCorruptedError(in: container,
debugDescription: "Invalid ISO8601 date: \(str)")
}
return decoder
}
}
// 3) 简易 ETag 缓存（内存演示，可替换为持久化方案）
final class ETagCache {
static let shared = ETagCache()
private var store: [String: (etag: String, data: Data)] = [:]
private let lock = NSLock()
func key(for url: URL) -> String { url.absoluteString }
func get(for url: URL) -> (etag: String, data: Data)? {
lock.lock(); defer { lock.unlock() }
return store[key(for: url)]
}
func set(for url: URL, etag: String, data: Data) {
lock.lock(); defer { lock.unlock() }
store[key(for: url)] = (etag, data)
}
}
// 4) 构建请求并发起调用
struct OrdersQuery {
var status: String? // "pending"/"paid"/"shipped"/"canceled"
var page: Int? // >= 1
var pageSize: Int? // <= 100
var updatedAfter: Date? // RFC3339/ISO8601
}
func fetchOrders(baseURL: URL,
token: String,
query: OrdersQuery,
completion: @escaping (Result<OrdersResponse, Error>) -> Void) {
// URLComponents 构建查询参数
var components = URLComponents(url: baseURL.appendingPathComponent("/api/v1/orders"), resolvingAgainstBaseURL: false)!
var items: [URLQueryItem] = []
if let status = query.status { items.append(URLQueryItem(name: "status", value: status)) }
if let page = query.page { items.append(URLQueryItem(name: "page", value: String(page))) }
if let pageSize = query.pageSize {
let clamped = min(pageSize, 100) // 客户端侧预防性限制
items.append(URLQueryItem(name: "page_size", value: String(clamped)))
}
if let updatedAfter = query.updatedAfter {
let fmt = ISO8601FlexibleDecoder.withFractional // 输出 RFC3339/ISO8601 字符串
let str = fmt.string(from: updatedAfter)
items.append(URLQueryItem(name: "updated_after", value: str))
}
components.queryItems = items
guard let url = components.url else {
completion(.failure(NSError(domain: "OrdersAPI", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid URL"])))
return
}
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
// 附加 If-None-Match（若有）
if let cached = ETagCache.shared.get(for: url) {
request.setValue(cached.etag, forHTTPHeaderField: "If-None-Match")
}
let task = URLSession.shared.dataTask(with: request) { data, response, error in
if let error = error {
completion(.failure(error)); return
}
guard let http = response as? HTTPURLResponse else {
completion(.failure(NSError(domain: "OrdersAPI", code: -2, userInfo: [NSLocalizedDescriptionKey: "No HTTP response"])))
return
}
// 304：返回缓存数据
if http.statusCode == 304 {
if let cached = ETagCache.shared.get(for: url) {
let decoder = ISO8601FlexibleDecoder.decoder()
do {
let result = try decoder.decode(OrdersResponse.self, from: cached.data)
completion(.success(result))
} catch {
completion(.failure(error))
}
} else {
completion(.failure(NSError(domain: "OrdersAPI", code: 304, userInfo: [NSLocalizedDescriptionKey: "Not Modified but no cache"])))
}
return
}
// 非 200：转化为错误（实际项目可按 401/403/422/500 分流处理）
guard http.statusCode == 200, let data = data else {
completion(.failure(NSError(domain: "OrdersAPI", code: http.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP \(http.statusCode)"])))
return
}
// 解析并存储 ETag
if let etag = http.value(forHTTPHeaderField: "ETag") {
ETagCache.shared.set(for: url, etag: etag, data: data)
}
let decoder = ISO8601FlexibleDecoder.decoder()
do {
let result = try decoder.decode(OrdersResponse.self, from: data)
completion(.success(result))
} catch {
completion(.failure(error))
}
}
task.resume()
}
// 5) 加载下一页示例
func loadNextPageIfNeeded(current: OrdersResponse, baseURL: URL, token: String, status: String?) {
guard current.meta.hasNext else { return }
let nextPage = current.meta.page + 1
let query = OrdersQuery(status: status, page: nextPage, pageSize: current.meta.pageSize, updatedAfter: nil)
fetchOrders(baseURL: baseURL, token: token, query: query) { result in
// 合并列表 UI...
}
}
注意事项
- 认证
- 必须在请求头中携带 Authorization: Bearer 。令牌无效或缺失将导致 401。
- 参数有效性
- page 必须为 >= 1；page_size 建议不超过 100（超过可能返回 422）。
- status 必须在指定枚举中；updated_after 必须符合 RFC3339。
- 时间与解析
- 响应字段 created_at 为 ISO8601 字符串；建议使用 ISO8601DateFormatter，并兼容是否包含毫秒。
- updated_after 建议使用 UTC（以 Z 结尾）提交。
- 货币与金额
- amount 为数值；建议在客户端使用 Decimal 进行金额计算/显示，避免浮点精度误差。
- currency 为 ISO-4217 代码（长度 3，例如 USD、CNY）。
- 分页
- 使用 meta.page、meta.page_size、meta.has_next 控制翻页逻辑；当 has_next 为 false 时停止继续请求。
- 缓存与 ETag
- 优先使用服务器下发的 ETag 与 If-None-Match 发起条件请求；当返回 304 时使用本地缓存数据，降低流量与延迟。
- 建议将 ETag 与响应体按完整 URL（含查询串）作为键进行缓存。
- 错误处理
- 401：引导用户重新登录或刷新令牌。
- 403：提示无权限操作。
- 422：提示参数不合法并回退到安全值（例如将 page 重置为 1，将 page_size 限制为 100）。
- 500：提示服务器错误并允许用户重试。
- 连接与安全
- 建议仅通过 HTTPS 访问并校验证书；设置合理的超时重试策略。
- 兼容性
- 若需要兼容不同的服务器时间格式，建议使用灵活的 ISO8601 解析策略（如示例所示），以提升鲁棒性。
