Documentation
¶
Index ¶
- Variables
- func ClearForTest()
- func FindCommandSettings[T any](appConfig *config.AppConfig, taskID contract.TaskID, ...) (*T, error)
- func FindTaskSettings[T any](appConfig *config.AppConfig, taskID contract.TaskID) (*T, error)
- func MustRegister(taskID contract.TaskID, cfg *TaskConfig)
- func NewErrCommandNotSupported(commandID contract.TaskCommandID, supportedCommandIDs []contract.TaskCommandID) error
- func NewErrTaskNotSupported(taskID contract.TaskID) error
- func NewErrTypeAssertionFailed(expected, got any) error
- func Register(taskID contract.TaskID, cfg *TaskConfig) error
- func RegisterForTest(taskID contract.TaskID, cfg *TaskConfig)
- type Base
- func (b *Base) Cancel()
- func (b *Base) CommandID() contract.TaskCommandID
- func (b *Base) Elapsed() time.Duration
- func (b *Base) ID() contract.TaskID
- func (b *Base) InstanceID() contract.TaskInstanceID
- func (b *Base) IsCanceled() bool
- func (b *Base) Log(component string, level applog.Level, message string, err error, ...)
- func (b *Base) NotifierID() contract.NotifierID
- func (b *Base) Run(ctx context.Context, notificationSender contract.NotificationSender)
- func (b *Base) RunBy() contract.TaskRunBy
- func (b *Base) Scraper() scraper.Scraper
- func (b *Base) SetExecute(execute ExecuteFunc)
- type ExecuteFunc
- type NewSnapshotFunc
- type NewTaskFunc
- type NewTaskParams
- type Registry
- type ResolvedConfig
- type Task
- type TaskCommandConfig
- type TaskConfig
- type Validator
Constants ¶
This section is empty.
Variables ¶
var ErrCommandConfigNil = apperrors.New(apperrors.InvalidInput, "Command 설정은 nil일 수 없습니다")
ErrCommandConfigNil Task 설정 내의 Command 설정 목록 중 nil 설정이 포함된 경우 반환되는 에러입니다.
var ErrCommandConfigsEmpty = apperrors.New(apperrors.InvalidInput, "최소 하나 이상의 Command 설정이 필요합니다")
ErrCommandConfigsEmpty Task 설정 내의 Command 설정이 하나도 없는 경우 반환되는 에러입니다.
var ErrCommandNotFound = apperrors.New(apperrors.NotFound, "해당 명령을 찾을 수 없습니다")
ErrCommandNotFound 지정된 Task 내에서 Command ID에 해당하는 Command를 찾을 수 없을 때 반환됩니다.
var ErrCommandNotSupported = apperrors.New(apperrors.InvalidInput, "지원하지 않는 명령입니다")
ErrCommandNotSupported 지원하지 않는 Command 요청 시 반환되는 기본 에러입니다.
var ErrDuplicateCommandID = apperrors.New(apperrors.Conflict, "중복된 CommandID입니다")
ErrDuplicateCommandID 동일한 Task 내에서 중복된 CommandID가 발견된 경우 반환되는 기본 에러입니다.
var ErrDuplicateTaskID = apperrors.New(apperrors.Conflict, "중복된 TaskID입니다")
ErrDuplicateTaskID 중복된 TaskID가 발견된 경우 반환되는 기본 에러입니다.
var ErrNewSnapshotNil = apperrors.New(apperrors.InvalidInput, "NewSnapshot 팩토리 함수는 필수값입니다")
ErrNewSnapshotNil NewSnapshot 팩토리 함수가 누락된 경우 반환되는 에러입니다.
var ErrNewTaskNil = apperrors.New(apperrors.InvalidInput, "NewTask 팩토리 함수는 필수값입니다")
ErrNewTaskNil NewTask 팩토리 함수가 누락된 경우 반환되는 에러입니다.
var ErrTaskConfigNil = apperrors.New(apperrors.InvalidInput, "Task 설정은 필수값입니다")
ErrTaskConfigNil Task 설정 등록 시 Task 설정 객체가 nil인 경우 반환되는 에러입니다.
var ErrTaskNotFound = apperrors.New(apperrors.NotFound, "해당 작업을 찾을 수 없습니다")
ErrTaskNotFound 지정된 Task ID에 해당하는 Task를 찾을 수 없을 때 반환됩니다.
var ErrTaskNotSupported = apperrors.New(apperrors.InvalidInput, "지원하지 않는 작업입니다")
ErrTaskNotSupported 지원하지 않는 Task 요청 시 반환되는 기본 에러입니다.
Functions ¶
func ClearForTest ¶
func ClearForTest()
ClearForTest 전역 Registry에 등록된 모든 Task 설정을 제거합니다.
테스트 간 격리를 위해 각 테스트 시작 시점에 호출하여 깨끗한 상태를 보장합니다.
경고: 이 메서드는 프로덕션 환경에서 절대 호출되어서는 안 됩니다. 실행 중인 서버의 모든 Task 설정이 삭제되어 서비스 장애로 이어질 수 있습니다.
func FindCommandSettings ¶
func FindCommandSettings[T any](appConfig *config.AppConfig, taskID contract.TaskID, commandID contract.TaskCommandID) (*T, error)
FindCommandSettings AppConfig에서 특정 Task 내의 Command에 해당하는 추가 설정 정보를 찾아 타입 T로 디코딩하고 검증합니다.
설정 정보 구조체가 Validator 인터페이스를 구현한 경우, 디코딩 후 자동으로 Validate 메서드를 호출하여 설정값의 유효성을 검증합니다.
파라미터:
- appConfig: 전체 애플리케이션 설정
- taskID: Task의 고유 식별자
- commandID: Command의 고유 식별자
반환값:
- *T: 디코딩되고 검증된 설정 정보 구조체 포인터 (성공 시)
- error: Task/Command를 찾지 못하거나, 디코딩 또는 유효성 검증에 실패한 경우 에러 반환
func FindTaskSettings ¶
FindTaskSettings AppConfig에서 특정 Task에 해당하는 추가 설정 정보를 찾아 타입 T로 디코딩하고 검증합니다.
이 함수는 제네릭을 사용하여 다양한 Task의 추가 설정 정보 타입을 안전하게 처리할 수 있습니다. 설정 정보 구조체가 Validator 인터페이스를 구현한 경우, 디코딩 후 자동으로 Validate 메서드를 호출하여 설정값의 유효성을 검증합니다.
파라미터:
- appConfig: 전체 애플리케이션 설정
- taskID: Task의 고유 식별자
반환값:
- *T: 디코딩되고 검증된 설정 정보 구조체 포인터 (성공 시)
- error: Task를 찾지 못하거나, 디코딩 또는 유효성 검증에 실패한 경우 에러 반환
func MustRegister ¶
func MustRegister(taskID contract.TaskID, cfg *TaskConfig)
MustRegister Task 설정을 전역 Registry에 등록하며, 실패 시 패닉을 발생시킵니다.
"Fail Fast" 원칙에 따라 애플리케이션 초기화 단계에서 잘못된 설정을 즉시 감지합니다. 주로 init() 함수나 main() 함수에서 호출되어 설정 오류를 사전에 차단합니다.
매개변수:
- taskID: 등록할 Task의 고유 식별자
- cfg: Task 설정 객체 (nil 불가)
func NewErrCommandNotSupported ¶
func NewErrCommandNotSupported(commandID contract.TaskCommandID, supportedCommandIDs []contract.TaskCommandID) error
NewErrCommandNotSupported 지원하지 않는 Command 요청 시 에러를 생성합니다.
매개변수:
- commandID: 요청된 Command의 고유 식별자
- supportedCommandIDs: 해당 Task가 지원하는 Command ID 목록 (빈 배열인 경우 목록 없이 기본 메시지만 표시)
반환값: 요청된 CommandID와 지원 가능한 Command ID 목록을 포함한 상세 에러 메시지
func NewErrTaskNotSupported ¶
NewErrTaskNotSupported 지원하지 않는 Task 요청 시 에러를 생성합니다.
매개변수:
- taskID: 요청된 Task의 고유 식별자
반환값: 요청된 TaskID를 포함한 상세 에러 메시지
func NewErrTypeAssertionFailed ¶
NewErrTypeAssertionFailed snapshot의 타입 단언 실패 시 에러를 생성합니다.
이 함수는 Command 실행 시 이전 실행 결과의 snapshot을 특정 타입으로 단언할 때 실패하는 경우 호출됩니다. 타입 불일치는 일반적으로 Command 설정 변경, snapshot 구조 변경, 또는 코드 버그로 인해 발생하는 내부 오류입니다.
매개변수:
- expected: 기대했던 snapshot 타입의 제로값 (타입 정보 추출용)
- got: 실제로 전달된 snapshot 값
반환값: 기대 타입과 실제 타입을 포함한 상세 에러 메시지
func Register ¶
func Register(taskID contract.TaskID, cfg *TaskConfig) error
Register Task 설정을 전역 Registry에 등록합니다.
매개변수:
- taskID: 등록할 Task의 고유 식별자
- cfg: Task 설정 객체 (nil 불가)
반환값:
- error: 유효성 검증 실패 또는 중복 ID 시 에러 반환, 성공 시 nil
func RegisterForTest ¶
func RegisterForTest(taskID contract.TaskID, cfg *TaskConfig)
RegisterForTest 유효성 검증 절차를 우회하여 Task 설정을 전역 Registry에 강제 등록합니다.
경고: 이 메서드는 프로덕션 환경에서 절대 호출되어서는 안 됩니다.
Types ¶
type Base ¶
type Base struct {
// contains filtered or unexported fields
}
Base 개별 Task의 실행 단위이자 상태를 관리하는 핵심 구조체입니다.
이 구조체는 Task의 정의(무엇을, 어떻게)와 실행 상태(언제, 얼마나)를 모두 캡슐화하며, Service 레이어에 의해 생성되고 생명주기가 관리됩니다.
func NewBase ¶
func NewBase(p NewTaskParams, requireScraper bool) *Base
NewBase NewTaskParams를 기반으로 Base 인스턴스를 생성하는 공개 팩토리 함수입니다.
이 함수는 개별 Task 구현체(kurly, naver, lotto 등)의 NewTask 메서드에서 호출되며, 반복적으로 나타나는 Base 초기화 코드를 간소화하여 코드 중복을 방지합니다. NewTaskParams를 내부 baseParams로 변환하고, 필요 시 Scraper를 초기화한 후 newBase() 내부 팩토리 함수를 호출하여 완전히 초기화된 Base 인스턴스를 반환합니다.
매개변수:
- p: Task 생성에 필요한 모든 매개변수를 담은 구조체
- requireScraper: 웹 스크래핑 기능 활성화 여부 (true로 설정 시 p.Fetcher가 필수이며, nil일 경우 패닉 발생)
반환값: 완전히 초기화된 Base 인스턴스 포인터
func (*Base) CommandID ¶
func (b *Base) CommandID() contract.TaskCommandID
func (*Base) InstanceID ¶
func (b *Base) InstanceID() contract.TaskInstanceID
func (*Base) IsCanceled ¶
func (*Base) Log ¶
func (b *Base) Log(component string, level applog.Level, message string, err error, fields applog.Fields)
Log 컴포넌트 이름, 에러, 추가 필드를 포함한 구조적 로깅을 수행합니다.
이 메서드는 Base 생성 시 바인딩된 기본 필드(task_id, command_id 등)에 추가적인 컨텍스트 정보를 덧붙여 로그를 기록합니다.
func (*Base) NotifierID ¶
func (b *Base) NotifierID() contract.NotifierID
func (*Base) Run ¶
func (b *Base) Run(ctx context.Context, notificationSender contract.NotificationSender)
Run Task의 전체 생명주기를 관리하는 메인 진입점입니다.
이 메서드는 Task 인터페이스의 핵심 메서드로서, Service 레이어에서 호출되어 Task의 생성부터 종료까지의 전체 생명주기를 제어합니다.
매개변수:
- ctx: Task 실행의 생명주기를 제어하는 컨텍스트 (타임아웃, 취소 신호 전파)
- notificationSender: 작업 결과를 사용자에게 알리기 위한 인터페이스 구현체 (필수)
func (*Base) SetExecute ¶
func (b *Base) SetExecute(execute ExecuteFunc)
type ExecuteFunc ¶
type ExecuteFunc func(ctx context.Context, previousSnapshot any, supportsHTML bool) (string, any, error)
ExecuteFunc Task의 핵심 비즈니스 로직을 수행하는 함수 타입입니다.
이 함수는 가능한 한 순수 함수(Pure Function)에 가깝게 구현되어야 합니다. 즉, 외부 상태를 직접 변경하지 않고, 입력(previousSnapshot)을 받아 처리한 후 결과(메시지, 새로운 Snapshot)를 반환하는 방식으로 동작해야 합니다.
매개변수:
- ctx: 작업 실행의 생명주기를 제어하는 컨텍스트 (취소, 타임아웃 처리)
- previousSnapshot: 이전 실행 시 저장된 작업 결과 데이터 (최초 실행 시 nil 또는 초기값)
- supportsHTML: 알림 대상 채널의 HTML 지원 여부
반환값:
- string: 사용자에게 전송할 알림 메시지 (빈 문자열일 경우 알림 전송 안 함)
- any: 다음 실행을 위해 저장할 새로운 작업 결과 데이터 (nil일 경우 저장 안 함)
- error: 실행 중 발생한 에러 (nil이 아니면 작업 실패로 처리되며 에러 알림 전송)
type NewSnapshotFunc ¶
type NewSnapshotFunc func() any
NewSnapshotFunc Task 작업 결과 데이터의 빈 인스턴스를 생성하는 팩토리 함수 타입입니다.
type NewTaskFunc ¶
type NewTaskFunc func(NewTaskParams) (Task, error)
NewTaskFunc 새로운 Task 인스턴스를 생성하는 팩토리 함수 타입입니다.
type NewTaskParams ¶
type NewTaskParams struct {
AppConfig *config.AppConfig
// Request 사용자가 제출한 Task 실행 요청 정보입니다.
Request *contract.TaskSubmitRequest
// InstanceID 실행 중인 Task의 고유 식별자입니다.
InstanceID contract.TaskInstanceID
// Storage Task 작업 결과 데이터를 영구 저장하기 위한 저장소 인터페이스입니다.
// 이전 작업 결과 조회 및 새로운 결과 저장에 사용됩니다.
Storage contract.TaskResultStore
// Fetcher HTTP 요청을 수행하는 인터페이스입니다.
Fetcher fetcher.Fetcher
// NewSnapshot Task 작업 결과 데이터의 빈 인스턴스를 생성하는 팩토리 함수입니다.
NewSnapshot NewSnapshotFunc
}
NewTaskParams 새로운 Task 생성에 필요한 매개변수들을 정의하는 구조체입니다.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 등록된 모든 Task와 Command 설정을 관리하는 중앙 저장소입니다.
이 구조체는 애플리케이션 시작 시점에 모든 Task 설정을 등록받아 저장하고, Task 실행 요청 시 해당 설정을 조회하여 제공하는 역할을 합니다. 동시성 제어를 위해 RWMutex를 사용합니다.
func (*Registry) ClearForTest ¶
func (r *Registry) ClearForTest()
ClearForTest Registry에 등록된 모든 Task 설정을 제거합니다.
테스트 간 격리를 위해 각 테스트 시작 시점에 호출하여 깨끗한 상태를 보장합니다.
경고: 이 메서드는 프로덕션 환경에서 절대 호출되어서는 안 됩니다. 실행 중인 서버의 모든 Task 설정이 삭제되어 서비스 장애로 이어질 수 있습니다.
func (*Registry) MustRegister ¶
func (r *Registry) MustRegister(taskID contract.TaskID, cfg *TaskConfig)
MustRegister Task 설정을 Registry에 등록하며, 실패 시 패닉을 발생시킵니다.
"Fail Fast" 원칙에 따라 애플리케이션 초기화 단계에서 잘못된 설정을 즉시 감지합니다. 주로 init() 함수나 main() 함수에서 호출되어 설정 오류를 사전에 차단합니다.
매개변수:
- taskID: 등록할 Task의 고유 식별자
- cfg: Task 설정 객체 (nil 불가)
func (*Registry) Register ¶
func (r *Registry) Register(taskID contract.TaskID, cfg *TaskConfig) error
Register Task 설정을 Registry에 등록합니다.
매개변수:
- taskID: 등록할 Task의 고유 식별자
- cfg: Task 설정 객체 (nil 불가)
반환값:
- error: 유효성 검증 실패 또는 중복 ID 시 에러 반환, 성공 시 nil
func (*Registry) RegisterForTest ¶
func (r *Registry) RegisterForTest(taskID contract.TaskID, cfg *TaskConfig)
RegisterForTest 유효성 검증 절차를 우회하여 Task 설정을 강제 등록합니다.
경고: 이 메서드는 프로덕션 환경에서 절대 호출되어서는 안 됩니다.
type ResolvedConfig ¶
type ResolvedConfig struct {
Task *TaskConfig
Command *TaskCommandConfig
}
ResolvedConfig Registry에서 조회된 Task와 Command 설정의 조합입니다.
Task 실행 요청 시 FindConfig를 통해 반환되며, Task 인스턴스 생성에 필요한 모든 설정을 포함합니다.
func FindConfig ¶
func FindConfig(taskID contract.TaskID, commandID contract.TaskCommandID) (*ResolvedConfig, error)
FindConfig 전역 Registry를 통해 주어진 Task ID와 Command ID에 해당하는 설정을 검색합니다.
매개변수:
- taskID: 검색할 Task의 고유 식별자
- commandID: 검색할 Command의 고유 식별자
반환값:
- *ResolvedConfig: 매칭된 Task와 Command 설정 (깊은 복사본)
- error: Task 또는 Command를 찾을 수 없는 경우
type Task ¶
type Task interface {
ID() contract.TaskID
CommandID() contract.TaskCommandID
InstanceID() contract.TaskInstanceID
// NotifierID 작업 완료 시 알림을 전송할 대상 채널의 식별자를 반환합니다.
NotifierID() contract.NotifierID
// Cancel 실행 중인 작업의 취소를 요청합니다.
// 호출 즉시 IsCanceled()가 true를 반환하며, Run 내부 로직은 이를 감지하여 조기 종료해야 합니다.
Cancel()
// IsCanceled 작업이 취소되었는지 여부를 반환합니다.
// Run 메서드 내부에서 주기적으로 확인하여 취소 시 작업을 중단하는 용도로 사용됩니다.
IsCanceled() bool
// Elapsed 작업 시작 시점부터 현재까지의 경과 시간을 반환합니다.
// 작업 시작 전에는 0을 반환합니다.
Elapsed() time.Duration
// Run Task의 핵심 비즈니스 로직을 실행합니다.
// 이 메서드는 동기적으로 실행되며, 작업이 완료되거나 취소될 때까지 블로킹됩니다.
// 비동기 실행이 필요한 경우 호출자가 goroutine과 동기화를 직접 관리해야 합니다.
Run(ctx context.Context, notificationSender contract.NotificationSender)
}
Task 개별 Task 인스턴스의 생명주기를 제어하고 상태를 조회하기 위한 인터페이스입니다.
이 인터페이스는 Service 레이어와 구체적인 Task 구현체(Base 기반) 사이의 계약을 정의합니다. Service는 구현 세부사항을 알 필요 없이 이 인터페이스만으로 Task를 실행, 취소, 모니터링할 수 있습니다.
type TaskCommandConfig ¶
type TaskCommandConfig struct {
// ID Command의 고유 식별자입니다.
ID contract.TaskCommandID
// AllowMultiple 동일 Command의 동시 실행 허용 여부입니다.
// - true: 동일 Command를 여러 인스턴스가 동시에 병렬 실행 가능
// - false: 이미 실행 중이면 새 요청 거부 (중복 실행 방지)
AllowMultiple bool
// NewSnapshot Task 작업 결과 데이터의 빈 인스턴스를 생성하는 팩토리 함수입니다.
NewSnapshot NewSnapshotFunc
}
TaskCommandConfig 개별 Command의 실행 정책과 데이터 관리 방식을 정의하는 구조체입니다.
func (*TaskCommandConfig) Clone ¶
func (c *TaskCommandConfig) Clone() *TaskCommandConfig
Clone Command 설정을 복제하여 반환합니다.
복사 방식:
- 이 구조체는 슬라이스나 맵 같은 가변 참조 타입을 포함하지 않습니다.
- 따라서 얕은 복사(Shallow Copy)만으로도 원본과 완전히 독립된 객체가 됩니다.
- NewSnapshot 함수는 불변이므로 포인터가 공유되어도 안전합니다.
type TaskConfig ¶
type TaskConfig struct {
// Commands Task가 수행할 수 있는 모든 Command의 목록입니다.
// 최소 1개 이상의 TaskCommandConfig가 필요하며, 각 Command는 독립적인 실행 단위입니다.
Commands []*TaskCommandConfig
// NewTask 새로운 Task 인스턴스를 생성하는 팩토리 함수입니다.
NewTask NewTaskFunc
}
TaskConfig Task 생성 및 Command 구성을 위한 메타데이터를 정의하는 구조체입니다.
역할 및 목적:
- Task의 "청사진(Blueprint)" 역할을 수행합니다.
- 하나의 Task가 수행할 수 있는 모든 Command 목록과 Task 생성 방법을 정의합니다.
- Registry에 등록되어 Task 실행 요청 시 참조됩니다.
불변성 보장:
- Registry 등록 시 Clone()을 통해 깊은 복사되어 저장됩니다.
- 등록 후에는 외부에서 원본을 수정하더라도 Registry 내부 상태에 영향을 주지 않습니다.
- 조회 시에도 Clone()을 통해 복사본을 반환하여 동시성 안전성을 보장합니다.
func (*TaskConfig) Clone ¶
func (c *TaskConfig) Clone() *TaskConfig
Clone Task 설정을 깊은 복사(Deep Copy)하여 반환합니다.
Registry에 등록된 원본 설정을 외부 변경으로부터 완벽하게 격리하기 위해 사용됩니다. 단순히 구조체만 복사하면 내부의 Commands 슬라이스가 원본과 메모리를 공유하게 되어, 복사본을 수정했을 때 원본 데이터까지 함께 변경되는 부작용(Side Effect)이 발생할 수 있습니다.
복사 방식:
- TaskConfig 구조체 자체를 얕은 복사 (기본 필드값 복제)
- Commands 슬라이스를 새로 할당 (메모리 공간 분리)
- 각 CommandConfig 요소를 재귀적으로 복제 (내부 객체까지 완전 분리)
Source Files
Directories