Skip to content

README.ko.md

Latest commit

 

History

History
361 lines (283 loc) · 11.7 KB

README.ko.md

File metadata and controls

361 lines (283 loc) · 11.7 KB

Nexa

Build Swift Platforms Swift Package Manager

English | 한국어

Nexa는 URLSession 기반의 SwiftUI 스타일 선언형 네트워킹 라이브러리입니다.

기능

  • GET, POST, PUT, PATCH, DELETE를 위한 선언형 요청 빌더
  • Swift Concurrency를 활용한 타입 안전 응답 디코딩
  • 값 타입 기반 요청 조합
  • 쿼리, 헤더, 타임아웃, 바디, JSON 인코딩 지원
  • 컴파일 타임 응답 타입을 갖는 Endpoint 기반 API
  • 요청 단위 및 전역 인터셉터 체인
  • NXAuthTokenProvider를 통한 인증 및 토큰 갱신 흐름 내장
  • Fixed backoff 및 exponential backoff 기반 재시도 정책
  • 응답 유효성 검사 및 서버 에러 디코딩
  • 로거 훅 및 테스트를 위한 transport 추상화

요구 사항

플랫폼 Swift 설치
iOS 15.0+ / macOS 12.0+ Swift 6.1 Swift Package Manager

설치

Swift Package Manager

Package.swift에 Nexa를 추가하세요:

dependencies: [
    .package(url: "https://github.com/opficdev/Nexa.git", branch: "main")
]

그런 다음 타겟 의존성에 Nexa를 추가하세요:

.target(
    name: "AppModule",
    dependencies: [
        .product(name: "Nexa", package: "Nexa")
    ]
)

공개 API

대부분의 코드는 NXAPIClient에서 시작하여 NXRequestBuilder 또는 NXTypedRequestBuilder<Response>로 이어집니다.

나머지 공개 인터페이스는 인증, 로깅, 테스트, 재시도, 유효성 검사, 커스텀 에러 매핑을 위한 확장 포인트로 구성됩니다.

API 사용 시점 예시
NXAPIClient 동일한 baseURL과 설정을 공유하는 요청의 주 진입점 client.get("/users", as: User.self).send()
NXRequestBuilder 조립된 URLRequest를 직접 확인하거나 디코딩 없이 NXRawResponse를 받고 싶을 때 try await client.get("/users").raw()
NXTypedRequestBuilder<Response> 응답을 Decodable 타입으로 바로 디코딩할 때 try await client.get("/users/1", as: User.self).send()
NXEndpoint 엔드포인트 정의를 재사용하고 응답 타입을 함께 관리할 때 try await client.send(UserEndpoint(identifier: 1))
NXClientConfiguration 공통 헤더, transport, 로거, 인증, 인코더, 디코더, 인터셉터를 한 번에 설정할 때 NXClientConfiguration(baseURL: url, authTokenProvider: yourAuthTokenProvider)
NXRetryPolicy 재시도 가능한 상태 코드나 전송 오류 시 재시도할 때 .retry(.init(maxAttempts: 3))
NXValidationPolicy 허용할 상태 코드가 기본값(200..<300)과 다를 때 .validate(.statusCodes([200, 201, 204]))
NXHTTPTransport 테스트용 스텁이 필요하거나 transport 구현을 교체할 때 NXClientConfiguration(baseURL: url, transport: yourStubTransport)
NXHTTPInterceptor 트레이싱이나 헤더 주입처럼 요청 전반에 적용되는 처리가 필요할 때 .intercept(yourInterceptor)
NXAuthTokenProvider .authorized() 요청에 토큰 조회 및 갱신 기능이 필요할 때 authTokenProvider: yourAuthTokenProvider
NXServerErrorDecoder 실패 응답을 도메인 에러로 디코딩할 때 serverErrorDecoder: yourServerErrorDecoder
NXLogger 구조화된 요청 생명주기 로깅이 필요할 때 logger: yourLogger
NXRawResponse Data와 HTTPURLResponse를 직접 다뤄야 할 때 let response = try await client.get("/users").raw()
NXError 호출 코드에서 Nexa 고유 오류를 처리할 때 catch let error as NXError
NXHTTPMethod NXEndpoint의 메서드를 정의할 때 var method: NXHTTPMethod { .post }

어디서 시작할까요?

아래에서 client는 이미 설정된 NXAPIClient라고 가정합니다.

대부분의 앱 코드에서는 NXAPIClient와 NXTypedRequestBuilder<Response> 조합을 사용할 수 있습니다.

import Foundation
import Nexa

struct User: Decodable {
    let id: Int
    let name: String
}

let user = try await client
    .get("/users/42", as: User.self)
    .send()

요청을 직접 확인하거나 원시 응답을 직접 처리할 때는 NXRequestBuilder를 사용하면 됩니다.

import Foundation
import Nexa

let request = try await client
    .post("/users")
    .header("X-Trace-Id", UUID().uuidString)
    .preparedURLRequest()

동일한 엔드포인트 형태가 여러 곳에서 재사용될 때는 NXEndpoint를 사용하면 됩니다.

import Foundation
import Nexa

struct User: Decodable {
    let id: Int
    let name: String
}

struct UserEndpoint: NXEndpoint {
    let identifier: Int

    var method: NXHTTPMethod { .get }
    var path: String { "/users/\(identifier)" }

    func configure(_ builder: NXTypedRequestBuilder<User>) -> NXTypedRequestBuilder<User> {
        builder.query("include", "profile")
    }
}

기본 동작으로 충분하지 않을 때만 하위 레벨 프로토콜을 사용하면 됩니다.

  • NXHTTPTransport: 스텁, 목, 커스텀 네트워크 백엔드
  • NXHTTPInterceptor: 트레이싱, 요청 변환, 커스텀 흐름 제어
  • NXAuthTokenProvider: bearer token 주입 및 갱신
  • NXServerErrorDecoder: 서버 payload를 도메인 에러로 매핑
  • NXLogger: 요청 생명주기 로깅 및 관측성

요청 흐름

sequenceDiagram
    autonumber
    participant App
    participant Config as NXClientConfiguration
    participant Client as NXAPIClient
    participant Builder as Builder
    participant Assembler as NXRequestAssembler
    participant Chain as NXInterceptorChain
    participant Transport as NXHTTPTransport
    participant Pipeline as NXResponsePipeline

    App->>Config: 공통 설정 구성
    App->>Client: NXAPIClient(configuration)

    alt method 기반 호출
        App->>Client: get/post/put/patch/delete
        Client->>Builder: NXRequestBuilder or NXTypedRequestBuilder
    else endpoint 기반 호출
        App->>Client: request(endpoint) / send(endpoint)
        Client->>Builder: endpoint.configure(builder)
    end

    App->>Builder: query/header/authorized/retry/validate/intercept...

    alt preparedURLRequest()
        Builder->>Assembler: assemble()
        Assembler-->>Builder: URLRequest
        Builder-->>App: URLRequest
    else raw()
        Builder->>Assembler: assemble()
        Assembler-->>Builder: URLRequest
        Builder->>Chain: execute(context)
        Chain->>Transport: send(request)
        Transport-->>Chain: NXRawResponse
        Chain-->>Builder: NXRawResponse
        Builder->>Pipeline: validate()
        Pipeline-->>Builder: validated
        Builder-->>App: NXRawResponse
    else send()
        Builder->>Assembler: assemble()
        Assembler-->>Builder: URLRequest
        Builder->>Chain: execute(context)
        Chain->>Transport: send(request)
        Transport-->>Chain: NXRawResponse
        Chain-->>Builder: NXRawResponse
        Builder->>Pipeline: validate()
        Pipeline-->>Builder: validated
        Builder->>Pipeline: decode()
        Pipeline-->>Builder: Response
        Builder-->>App: Response
    end
Loading

빠른 시작

Nexa는 인증, 재시도, 유효성 검사, 디코딩을 하나의 흐름으로 간결하게 표현합니다.

import Foundation
import Nexa

struct User: Decodable {
    let id: Int
    let name: String
}

let client = NXAPIClient(
    configuration: NXClientConfiguration(
        baseURL: URL(string: "https://api.example.com")!
    )
)

let user = try await client
    .get("/users/me", as: User.self)
    .query("include", "profile")
    .accept("application/json")
    .send()

.authorized()는 클라이언트에 authTokenProvider가 설정된 경우에만 추가하세요.

단계별로 요청을 구성할 수도 있습니다:

import Foundation
import Nexa

struct CreateUserPayload: Encodable {
    let name: String
}

struct User: Decodable {
    let id: Int
    let name: String
}

let createdUser = try await client
    .post("/users", as: User.self)
    .header("X-Trace-Id", UUID().uuidString)
    .json(CreateUserPayload(name: "opfic"))
    .send()

Endpoint API

Moya 스타일의 엔드포인트 추상화를 선호한다면, NXEndpoint를 정의하여 응답 타입을 엔드포인트에 직접 연결할 수 있습니다.

import Foundation
import Nexa

struct User: Decodable {
    let id: Int
    let name: String
}

struct UserEndpoint: NXEndpoint {
    let identifier: Int

    var method: NXHTTPMethod { .get }
    var path: String { "/users/\(identifier)" }

    func configure(_ builder: NXTypedRequestBuilder<User>) -> NXTypedRequestBuilder<User> {
        builder
            .query("include", "profile")
            .accept("application/json")
    }
}

let user = try await client.send(UserEndpoint(identifier: 42))

설정

NXClientConfiguration은 커스텀 API 레이어에 흩어지기 쉬운 설정을 한 곳에 집중시킵니다.

import Foundation
import Nexa

let configuration = NXClientConfiguration(
    baseURL: URL(string: "https://api.example.com")!,
    headers: [
        "Accept": "application/json"
    ],
    transport: NXURLSessionTransport(),
    logger: NXNoopLogger(),
    interceptors: [],
    serverErrorDecoder: NXDefaultServerErrorDecoder(),
    authTokenProvider: nil
)

let client = NXAPIClient(configuration: configuration)

커스텀 동작이 필요할 때만 기본값을 직접 구현한 타입으로 교체하세요:

  • NXLogger: 구조화된 로깅
  • NXHTTPInterceptor: 요청 트레이싱 또는 변환
  • NXServerErrorDecoder: 실패 응답을 도메인 에러로 매핑
  • NXAuthTokenProvider: bearer token 주입 및 갱신

현재 Nexa가 지원하는 기능:

  • 전역 헤더 및 요청별 헤더
  • 원시 바디 및 JSON 바디 인코딩
  • 요청 단위 유효성 검사 정책
  • .authorized() 요청에 대한 자동 인증 헤더 주입
  • 토큰 갱신 및 재시도 처리
  • 스터빙 및 격리 테스트를 위한 커스텀 transport

테스트

Nexa는 요청 실행을 테스트하기 쉽도록 설계되었습니다. NXHTTPTransport를 통해 실제 네트워킹을 커스텀 transport로 교체하고 발신 요청과 디코딩된 응답을 검증할 수 있습니다.

import Foundation
import Nexa

struct User: Codable, Equatable {
    let id: Int
    let name: String
}

struct StubTransport: NXHTTPTransport {
    func send(_ request: URLRequest) async throws -> NXRawResponse {
        let response = HTTPURLResponse(
            url: request.url!,
            statusCode: 200,
            httpVersion: nil,
            headerFields: nil
        )!

        return NXRawResponse(
            data: Data(#"{"id":1,"name":"opfic"}"#.utf8),
            response: response
        )
    }
}

let client = NXAPIClient(
    configuration: NXClientConfiguration(
        baseURL: URL(string: "https://example.com")!,
        transport: StubTransport()
    )
)

let user = try await client.get("/users/1", as: User.self).send()