이벤트와 비동기 작업 처리하기
업무 저장과 이벤트 발행을 묶고 같은 앱의 소비자에서 중복 없이 처리합니다.
이벤트와 비동기 작업 처리하기
법인 소유 Note를 수정한 뒤 비동기로 처리 확인 행을 만드는 예제입니다. Resource 만들기의 Workshop Note와 활성 샌드박스가 필요합니다. 이 예제의 EventReceipt는 개인정보 없는 테스트용 시스템 기록이며 실제 업무 기록의 권한 설계를 대신하지 않습니다.
이벤트와 결과 리소스 선언
앱 폴더에서 결과 확인용 테넌트 공통 리소스를 생성합니다.
nexia make resource EventReceipt --record-owner tenant --label-ko '이벤트 수신 기록'src/Descriptors/WorkshopEvents.php를 추가합니다. 생성된 Manifest는 src/Descriptors를 발견합니다. 같은 이벤트를 Resource lifecycle과 독립 descriptor에 중복 선언하지 마세요.
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Descriptors;
use Nexia\AppDescriptors\AppDescriptorSet;
use Nexia\AppDescriptors\Contracts\AppDescriptorContribution;
use Nexia\AppDescriptors\EventDescriptor;
final class WorkshopEvents implements AppDescriptorContribution
{
public static function appDescriptors(): AppDescriptorSet
{
return AppDescriptorSet::of(new EventDescriptor(
key: 'workshop.note.updated',
schemaVersion: 1,
aggregateType: 'workshop.note',
payloadSchema: [
'note_public_id' => ['type' => 'string', 'format' => 'uuid', 'required' => true],
],
));
}
}이 선언은 이벤트의 이름·producer 소유권·payload 계약을 공개합니다. Process 편집기 선택 목록에 공개하는 설정은 별도이며 이 예제에서는 켜지 않습니다.
저장과 발행을 같은 트랜잭션에 넣기
NoteController의 기존 update()에서 권한·입력 검증을 끝낸 뒤 단독 $note->update($validated)를 아래로 바꿉니다. 이미 수정된 Note를 또 저장하는 코드를 추가하지 마세요. 기존 응답 처리는 유지합니다.
use Illuminate\Support\Facades\DB;
use Nexia\Events\Contracts\EventPublisher;
use Nexia\Events\EventDraft;
use Nexia\Events\LegalEntityScope;
DB::transaction(function () use ($note, $validated): void {
$note->update($validated);
app(EventPublisher::class)->publish(new EventDraft(
eventName: 'workshop.note.updated',
payload: ['note_public_id' => (string) $note->public_id],
legalEntityScope: LegalEntityScope::explicit((int) $note->legal_entity_id),
aggregateType: 'workshop.note',
aggregateId: (string) $note->public_id,
schemaVersion: 1,
));
});현재 예제는 법인 소유 Note만 대상으로 합니다. publish()는 업무 저장과 함께 발행 의도를 기록하며 소비 완료를 의미하지 않습니다. 요청의 테넌트·실행 출처는 플랫폼이 복원합니다. Provider boot·일반 CLI·fixture에서 인증된 업무 요청을 가장해 발행하지 마세요.
소비자 구현과 등록
src/Events/RecordNoteUpdate.php를 추가합니다. 소유 앱에서 처리하는 시스템 기록이므로 사용자 위임 동작으로 사용하지 않습니다.
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Events;
use Illuminate\Support\Str;
use InvalidArgumentException;
use Nexia\Apps\Acme\Workshop\Models\EventReceipt;
use Nexia\Events\Contracts\InboxConsumer;
use Nexia\Events\EventEnvelope;
final class RecordNoteUpdate
{
public const KEY = 'workshop.note.update_receipt';
public function handle(EventEnvelope $event): void
{
if ($event->producerAppKey !== 'workshop'
|| $event->eventName !== 'workshop.note.updated'
|| $event->schemaVersion !== 1
|| ! is_string($event->payload['note_public_id'] ?? null)
|| ! Str::isUuid($event->payload['note_public_id'])) {
throw new InvalidArgumentException('Unexpected Note event.');
}
$result = app(InboxConsumer::class)->run($event, self::KEY, function () use ($event): void {
EventReceipt::firstOrCreate(
['public_id' => $event->identityUuid()],
['name' => 'Note updated'],
);
});
if ($result->error !== null) {
throw $result->error;
}
}
}src/WorkshopServiceProvider.php의 기존 boot()에 다음 등록을 추가합니다. import는 파일 상단에 넣고 기존 코드는 유지하세요. boot에서는 테넌트 데이터 조회나 쓰기를 하지 않습니다.
use Nexia\Apps\Acme\Workshop\Events\RecordNoteUpdate;
use Nexia\Events\Contracts\AppEventListeners;
use Nexia\Events\EventConsumerRegistration;
use Nexia\Events\EventRecoveryMode;
$this->app->make(AppEventListeners::class)->listen(
'workshop',
'outbox:workshop.note.updated',
RecordNoteUpdate::class,
new EventConsumerRegistration(
consumerKey: RecordNoteUpdate::KEY,
recoveryMode: EventRecoveryMode::Replay,
supportedSchemaVersion: 1,
),
);Inbox의 처리 표시와 앱 쓰기는 같은 앱 트랜잭션에 묶입니다. 별도 업무 경로로도 같은 효과를 만들 수 있다면 추가 업무 멱등 키가 필요합니다. 이 예제는 Event identity로 행도 유일하게 만들고 같은 수신을 다시 처리해도 중복하지 않습니다. 외부 API 호출은 DB rollback으로 되돌릴 수 없습니다.
실제 전달 확인
nexia dev에서 소스·migration·이벤트 등록 준비가 끝날 때까지 기다립니다.- Note 수정 권한과 결과 Resource 조회 권한을 사용자에게 부여합니다.
- Note 한 건을 수정하고 이벤트 수신 기록 목록을 다시 조회합니다. 새 행이 생기기 전에는 소비 완료로 판단하지 않습니다.
- 별도 테스트에서는 같은 EventEnvelope를 소비자에 두 번 전달해 행이 한 건인지 확인합니다. 서로 다른 Note 수정은 별도 이벤트입니다.
- 저장 트랜잭션을 의도적으로 실패시키는 테스트에서는 업무 변경과 발행이 모두 취소돼야 합니다. 소비자 실패·앱 비활성화 이후 복구에서는 중복 효과가 없어야 합니다.
로컬 문법·mock 검사와 샌드박스 전달 성공을 구분하세요. 기록이 생기지 않으면 선택된 소스 버전, 이벤트 이름, consumer key, runtime 준비 상태를 확인하고 작업 식별자로 지원을 요청합니다. DB나 Inbox 상태를 직접 변경하지 않습니다.
권한과 복구 방식 선택
| 상황 | 계약 |
|---|---|
| 사용자 위임과 무관한 시스템 기록 | 이 예제의 AppEventListeners |
| 사용자를 대신하는 보호 업무 | ActorDelegatedAppEventListeners와 EventActorAuthorizer로 실행 직전 재인가 |
| 중단 동안의 사실을 다시 처리 | Replay |
| 현재 상태로 다시 맞춤 | Reconcile과 별도로 등록한 멱등 reconciler |
| 누락을 의도적으로 허용 | Ephemeral |
actor ID만으로 사용자의 권한을 대신하지 않습니다. 다른 앱의 이벤트는 활성 공개 계약과 정확한 schema version이 필요하며, 원본 모델을 가져오지 않습니다. 일반 큐 Job·예약 작업은 이 이벤트 예제와 다른 등록·실행 계약입니다. App 간 연동 방식 선택하기에서 현재 조회와 과거 사실 전달을 구분하세요.
명시적인 작업 요청·cron 선언은 백그라운드·예약 작업 실행하기를 따릅니다.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.
이벤트 처리의 업무 시간대
이벤트 핸들러와 재조정 콜백에서는 app(\Nexia\Tenancy\Contracts\TenantSettings::class)->businessTimezone()으로 테넌트 업무 시간대를 조회합니다. 플랫폼이 실행 문맥을 제공하므로 사용자나 시간대를 앱에서 임의로 지정하지 않습니다. Core 0.8.162를 먼저 적용한 뒤 Manager 0.1.0-alpha.88과 재빌드한 App 런타임 이미지를 적용해야 합니다. Manager만 갱신하면 기존 App 컨테이너에는 반영되지 않으며 SDK 변경은 필요하지 않습니다. 실패했던 이벤트는 수정 적용 후 기존 Inbox 복구 절차로 재처리하고, 새 문서를 중복 상신하거나 DB 상태를 직접 변경하지 마세요.