Core 결과 모델

Hive Axyl SDK 메서드는 호출 실패를 예외가 아니라 결과 객체로 반환합니다. 결과 객체는 IAxylResult를 구현하며, try/catch 대신 switch 구문으로 분기합니다. 앱 코드를 고쳐야 하는 문제는 예외로 발생하며, 발생 조건은 예외에 정리되어 있습니다.

메서드마다 전용 결과 타입이 있습니다. 예를 들어 CreateGuestAsync()는 AuthCreateGuestResult를 반환하고, 그 안에 Success와 기능별 결과가 중첩 클래스로 들어 있습니다.

결과 갈래

모든 결과 타입은 아래 네 갈래로 나뉩니다.

갈래	구체 타입	의미	처리
`Success`	`XxxResult.Success`	호출이 성공했습니다.	`Data`에서 응답 데이터를 사용합니다.
`Outcome`	`XxxResult.<결과 이름>`	호출이 끝까지 진행되어 기능 관점의 결과가 확정됐습니다. 서버 모듈은 서버가, Add-on은 스토어나 운영 체제가 결과를 정합니다.	결과별로 사용자 안내나 대체 흐름을 제공합니다.
`UnknownOutcome`	`XxxResult.UnknownOutcome`	이 SDK 버전이 알지 못하는 새 결과입니다.	로깅한 뒤 실패로 간주해 보수적으로 처리합니다.
`Failure`	`XxxResult.Failure`	네트워크 단절, 시간 초과, 호출 취소처럼 호출을 마치지 못했거나, 서버가 응답했지만 기능 관점의 결과가 아닌 경우입니다.	`Problem`의 HiveError로 원인을 확인합니다.

각 메서드가 어떤 Outcome을 선언하는지는 해당 메서드의 레퍼런스에 실려 있습니다.

플래그로 확인하기

구체 타입을 알 수 없는 공통 처리 코드에서는 IAxylResult의 두 플래그로 갈래를 구분합니다.

갈래	`IsSuccess`	`IsUntypedProblem`
`Success`	`true`	`false`
`Outcome`	`false`	`false`
`UnknownOutcome`	`false`	`false`
`Failure`	`false`	`true`

두 플래그가 동시에 true가 되는 경우는 없습니다. IsUntypedProblem이 false라고 해서 성공한 것은 아니므로, Outcome과 UnknownOutcome은 구체 타입으로 따로 분기해야 합니다.

분기 예시

Unity

AuthCreateGuestResult result = await auth.CreateGuestAsync(request);

switch (result)
{
    case AuthCreateGuestResult.Success success:
        // success.Data : GuestCreateResponseData
        break;

    // 이 메서드가 선언한 Outcome 중 앱이 대응할 결과만 분기합니다.
    case AuthCreateGuestResult.IpBlocked:
        break;

    case AuthCreateGuestResult.Failure failure:
        HiveError err = failure.Problem;
        // err.Code, err.Message, err.ExternalCode
        break;

    case AuthCreateGuestResult.UnknownOutcome unknown:
        // unknown.Code, unknown.RawJson을 기록한 뒤 실패로 처리합니다.
        break;

    // 안전망: 앱이 따로 대응하지 않는 Outcome
    default:
        break;
}

UNKNOWN과 FAILURE는 서버 값이 아닙니다

메서드 레퍼런스의 결과 케이스 표에서 UnknownOutcome과 Failure의 와이어 코드로 표기한 UNKNOWN과 FAILURE는 SDK가 부여한 구분자이며 서버가 보내는 값이 아닙니다. 서버가 보낸 실제 코드는 UnknownOutcome.Code와 Failure.Problem.ExternalCode에 담깁니다.

IAxylResult

interface — 네임스페이스 Hive.Axyl.Core

모든 결과 객체가 구현하는 인터페이스입니다. 모듈과 무관하게 결과를 공통으로 처리할 때 사용합니다.

읽기 전용입니다. SDK가 생성한 결과 타입만 구현하며, 앱 코드가 직접 구현하는 용도가 아닙니다. 마이너 릴리스에서 멤버가 추가될 수 있습니다.

프로퍼티

프로퍼티	타입	설명
`IsSuccess`	`bool`	호출이 성공했으면 `true`입니다.
`IsUntypedProblem`	`bool`	`Failure`이면 `true`입니다. 기능 관점의 `Outcome`은 포함하지 않습니다.
`UntypedProblem`	`HiveError?`	`Failure`의 상세 정보입니다. `IsUntypedProblem`이 `true`일 때만 값이 담깁니다.
`RawResponse`	`string?`	이 결과를 만들 때 사용한 원본 응답 본문입니다.

UntypedProblem은 Failure.Problem과 같은 값입니다. 구체 타입으로 분기했다면 Failure.Problem이 더 읽기 쉽고, 모듈에 무관한 공통 처리 코드에서는 UntypedProblem이 편합니다.

RawResponse의 용도

RawResponse는 네 갈래 모두에서 사용할 수 있습니다. SDK를 다시 생성하지 않고도 서버가 새로 추가한 필드를 읽을 수 있게 해 주는 값입니다. 전송 실패처럼 응답 본문을 받지 못한 경우에만 null입니다.

이 값은 앞으로의 호환성을 위한 참고 정보입니다. 어떤 결과인지 판별하는 기준으로 사용하지 마세요. 분기는 항상 결과 코드와 구체 타입을 기준으로 하세요.

AxylResultBase

class — 네임스페이스 Hive.Axyl.Core

SDK가 생성한 모든 결과 타입의 추상 기반 클래스입니다. IAxylResult를 구현하며, 앞서 설명한 네 갈래 중 하나만 성립하도록 보장합니다.

앱 코드가 직접 다룰 일은 없습니다. 결과 타입의 공통 프로퍼티가 어디에서 오는지 확인할 때만 참고하세요.

마커 인터페이스

특정 성격의 결과를 모듈에 무관하게 한 번에 걸러내는 데 사용합니다. 네임스페이스는 모두 Hive.Axyl.Contracts.Result입니다.

IUnknownOutcome

interface

SDK가 알지 못하는 새 결과 코드를 표시합니다. 생성된 UnknownOutcome 변형이 이 인터페이스를 구현합니다.

프로퍼티	타입	필수 여부	설명
`Code`	`string`	Required	서버 응답에 담긴, SDK가 인식하지 못한 결과 코드입니다.
`RawJson`	`string`	Required	원본 JSON 본문입니다. 앱이 직접 해석해야 할 때 사용합니다.

Unity

if (result is IUnknownOutcome unknown)
{
    // unknown.Code, unknown.RawJson을 로깅한 뒤 실패로 처리합니다.
}

IUntypedProblem

interface

기술적 실패를 표시합니다. 요청이 목적지에 도달하지 못했거나, 응답을 받았지만 SDK가 기능 관점의 결과로 해석하지 못한 경우입니다. 네트워크 실패, 전송 시간 초과, CancellationToken에 의한 취소, 네이티브 SDK의 사전 조건 위반(초기화 전, 미지원 플랫폼)이 여기에 해당합니다.

서버를 호출하는 모듈과 Add-on 모두에 적용됩니다. 생성된 Failure 변형이 이 인터페이스를 구현합니다.

프로퍼티	타입	필수 여부	설명
`Problem`	HiveError	Required	실패의 상세 정보입니다.

Unity

if (result is IUntypedProblem problem)
{
    ShowError(problem.Problem);
}

IUserCanceledOutcome

interface

앱 사용자가 OS나 인증 제공자의 화면을 직접 닫아 취소한 결과를 표시합니다. Apple 로그인 대화 상자를 닫거나 Credential Manager 시트를 취소한 경우가 여기에 해당합니다.

프로퍼티는 없으며, 타입 확인만으로 사용합니다.

코드로 취소한 것은 이 마커가 아닙니다

이 마커는 OS 화면 수준의 사용자 취소만 나타냅니다. CancellationToken이나 세션 취소 메서드로 코드가 취소한 경우는 Cancelled 코드를 담은 Failure로 분류되며, 이 마커가 붙지 않습니다.

Unity

if (result is IUserCanceledOutcome)
{
    // 사용자가 직접 닫았으므로 오류 메시지를 띄우지 않습니다.
}