Go용 Durable Task SDK를 사용하면 오케스트레이션, 활동, durable 엔터티를 Go 함수로 정의할 수 있습니다. 애플리케이션을 자신만의 컴퓨트 플랫폼에 호스팅하세요. Durable Task Scheduler는 실행 기록을 저장하고 Go 작업자에게 작업을 발송합니다.
Important
Go SDK는 베타 버전입니다. 이 글과 Go 퀵스타트 는 v1.0.0-beta3를 사용합니다. 베타는 v0.6.0을 바로 대체 가능한 버전이 아닙니다: 임베디드 SQLite, PostgreSQL 백엔드, 또는 독립형 gRPC 호스트를 지원하지 않습니다. Go는 Durable Functions 언어가 아닙니다.
전제 조건 및 설치
- Go 1.25 이상.
- Durable Task Scheduler 에뮬레이터용 Docker 또는 호환 가능한 컨테이너 런타임
- Azure의 경우 기존 스케줄러와 작업 허브, 그리고 Durable Task Data Contributor 역할이 있는 아이덴티티. 신원 기반 액세스를 참조하세요.
기존 Go 모듈에서 출시된 베타 버전을 설치하세요:
go get github.com/microsoft/durabletask-go@v1.0.0-beta3
SDK를 코드에 추가한 후, 전이 의존성과 체크섬을 기록하기 위해 go mod tidy를 실행하세요.
워커를 시작하고, 병렬 활동을 예약하며, 결과를 읽고, 종료하는 완전한 애플리케이션에 대해서는 Durable Task SDKs를 사용하여 앱 만들기 - Go를 참고하세요.
프로그래밍 모델
SDK는 하나의 Go 모듈로 제공됩니다. 주요 패키지는 다음과 같습니다:
| Package | Purpose |
|---|---|
task |
오케스트레이션, 활동, 엔터티 컨텍스트; 작업 등록; 지속 워크플로우 기본 요소. |
durabletaskscheduler |
Durable Task Scheduler용 연결 옵션 및 별도의 클라이언트와 작업자 연결 |
client |
동시성, 버전 관리, 작업 항목 필터 등 워커 구성. |
api |
인스턴스 및 엔티티 ID, 오케스트레이션 메타데이터, 관리 요청 옵션. |
오케스트레이터의 시그니처는 func(*task.OrchestrationContext) (any, error)입니다. 활동에는 func(task.ActivityContext) (any, error) 시그니처가 있습니다. 함수 기반 엔터티는 시그니처 func(*task.EntityContext) (any, error)를 가집니다.
GetInput로 타입이 지정된 입력을 읽고 직렬화 가능한 결과나 오류를 반환합니다. JSON이 기본 데이터 형식입니다.
작업 등록 및 실행
task.NewTaskRegistry로 레지스트리를 만드세요.
AddEntityN, AddOrchestratorN, AddActivityN로 스테이블 이름을 등록하고 등록 오류를 확인하세요. 활동 호출과 클라이언트 예약에 사용되는 이름은 등록 정보와 일치해야 합니다.
durabletaskscheduler.NewOptionsFromConnectionString로 연결 문자열을 파싱합니다. 옵션을 다음으로 넘기세요:
-
durabletaskscheduler.NewClient오케스트레이션 인스턴스를 시작하고 관리합니다. -
durabletaskscheduler.NewWorker등록된 작업을 실행합니다.
작업자에서 Start를 호출하여 작업 항목 처리를 시작하세요. 레지스트리에서 워커 라우팅 필터를 도출하려면 client.WithAutoWorkItemFilters()를 사용하세요. 다른 애플리케이션에서만 등록된 작업을 워커가 가져가 처리하지 못하게 하세요.
클라이언트와 작업자는 별도의 연결을 가지고 있습니다. 완료되면 클라이언트를 종료하세요. 애플리케이션의 실행 컨텍스트가 만료되면 새 bounded context를 사용하여 워커 Shutdown를 드레인합니다. 퀵스타트는 두 작업 모두에서 발생하는 오류를 확인합니다.
결정론적 오케스트레이터를 작성하세요
Durable 작업에 오케스트레이션 컨텍스트를 사용하세요:
| Operation | Go API | 자세히 알아보기 |
|---|---|---|
| 활동 순서 | ctx.CallActivity(...).Await(&result) |
함수 체이닝 |
| 팬아웃 및 팬인 | 모든 작업을 예약한 후 ctx.WhenAll(tasks...)한 다음 Await로 결과를 읽으세요. |
팬아웃/팬인 |
| Delay | ctx.CreateTimer(duration).Await(nil) |
지속성 타이머 |
| 이벤트를 기다리세요 | ctx.WaitForSingleEvent(name, timeout).Await(&result) |
외부 이벤트 |
| 자식 워크플로우를 호출합니다 | ctx.CallSubOrchestrator(...).Await(&result) |
하위 오케스트레이션 |
| 작업 다시 시도 | task.WithActivityRetryPolicy |
오류 처리 및 재시도 |
| 새로운 기록을 시작해 | ctx.ContinueAsNew |
영구 오케스트레이션 |
| 진행 상황 보고 | ctx.SetCustomStatusValue |
커스텀 상태 |
| 어떤 엔터티에 전화하거나 신호를 보내세요 |
ctx.CallEntity 및 ctx.SignalEntity |
지속성 엔터티 |
네트워크 호출, 파일 I/O, 환경 변수 읽기 또는 기타 비결정적 작업을 오케스트레이터에서 수행하지 마세요. 그 작업을 활동으로 옮기세요. 오케스트레이터 코드에서는 네이티브 고루틴, 채널, sync.WaitGroup, 또는 time.Sleep 대신 SDK의 내구성 있는 동시성 원시 요소를 사용하세요. replay-aware 로깅에 ctx.Logger()를 사용하세요. 자세한 내용은 Orchestrator 코드 제약 조건을 참조하세요.
활동은 일반적인 Go I/O를 수행할 수 있지만, 두 번 이상 실행될 수 있습니다. 외부 부작용을 멱등하게 만드세요.
읽기 완료 결과
WaitForOrchestrationCompletion 오류 없이 반환된다는 것은 인스턴스가 터미널 상태에 도달했다는 의미이지, 워크플로우가 반드시 성공했다는 의미는 아닙니다. 페이로드를 api.WithFetchPayloads(true) 요청하고 api.RUNTIME_STATUS_COMPLETED가 RuntimeStatus인지 확인한 후 출력을 ReadOutput로 디코딩합니다.
실패한 인스턴스의 경우, FailureDetails를 검사하세요. 실패하거나 종료된 오케스트레이션을 성공적인 결과로 보고하지 마세요.
인스턴스 관리를 참조하세요.
에뮬레이터나 Azure에 연결하세요
퀵스타트는 연결 문자열 Endpoint=http://localhost:8080;TaskHub=default;Authentication=None를 사용합니다.
Authentication=None를 로컬 에뮬레이터 개발용으로 사용하세요. 인증된 Azure 접근용이 아닙니다.
Azure에서는 스케줄러의 HTTPS 엔드포인트와 작업 허브 이름을 사용하세요.
Authentication=AzureCLI Azure Identity 자격 증명 체인을 선택하거나, Azure CLI를 통해 로그인한 개발 식별 정보에는 Authentication=DefaultAzure를 선택하세요. Go SDK는 관리형 ID와 워크로드 ID도 지원합니다. 구성 세부사항과 지원 인증 모드는 Go SDK 연결 가이드를 참조하세요.
퀵스타트는 DTS_CONNECTION_STRING 환경 변수에서 연결 문자열을 읽어 NewOptionsFromConnectionString에 전달합니다. SDK가 이 변수를 자동으로 읽지 않습니다.
Samples
Go SDK 저장소에는 활동 시퀀스, 팬아웃/팬인, 외부 이벤트, 재시도, 내구성 엔터티, 일정, 대규모 페이로드, 히스토리 내보내기, 분산 추적 등 기능 영역별 실행 가능한 샘플이 포함되어 있습니다. 전체 목록, 전제 조건, 실행 지침은 Go SDK 샘플을 참조하세요.
테스트 오케스트레이션
SDK에는 스토리지 백엔드가 포함되어 있지 않아, 오케스트레이션은 Durable Task Scheduler 또는 그 에뮬레이터에서만 실행됩니다. 일반적인 Go 단위 테스트로 액티비티 및 기타 비즈니스 로직을 테스트합니다. 오케스트레이션 동작을 검증하려면 리플레이를 포함해 에뮬레이터나 전용 작업 허브에 대한 통합 테스트를 실행하세요.
베타 호환성 고려사항
- 스케줄: Go 스케줄은 다른 SDK와 영속화된 상태 형식을 공유하지 않습니다. 예약된 작업에는 Go 전용 작업 허브를 사용합니다.
- 엔티티 락: Go와 Python은 .NET와는 다른 다중 엔티티 락 순서를 사용합니다. Go/Python과 .NET 오케스트레이션에서 동시에 겹치는 잠금 세트를 획득하지 마세요.
- 되감기: Go 워커는 실패한 액티비티나 자식 작업 후에 추가적인 비생주기 사건이 포함된 히스토리를 보수적으로 거부합니다. 되감기 요청이 수락되었다고 해서 복구가 증명되는 것은 아닙니다; 새로운 실행 ID와 성공적인 출력을 검증하세요.
- 에뮬레이터 관리 API: 인스턴스 목록과 필터링된 삭제에는 에뮬레이터 제한 사항이 문서화되어 있습니다. 인스턴스 범위별 정리를 선호하고, 공유 허브를 비우지 마세요.
- 히스토리 내보내기(미리보기): 분리된 Go-only 작업 허브와 목적지를 사용해 내보내기 작업이 관련 없는 애플리케이션 데이터를 내보내거나 삭제하지 못하도록 하세요.
자세한 호환성과 라이프사이클 동작은 Go SDK 기능 매트릭스 및 전송 가이드 를 참조하세요.