백그라운드·예약 작업 실행하기
작업 선언·실행 요청·예약과 실제 처리 결과를 확인합니다.
백그라운드·예약 작업 실행하기
앱 자체의 queue worker나 서버 cron을 설치하지 않고 AppWorkContribution과 AppWorkDispatcher를 사용합니다. 개발 데이터 만들기의 테넌트 소유 Example 리소스를 준비하세요. 여기서는 고정된 예제 레코드 하나만 생성합니다. 사용자 권한을 위임받아 수행하는 업무 예제가 아닙니다.
작업 구현과 선언
src/Work/EnsureExample.php를 만듭니다:
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Work;
use InvalidArgumentException;
use Nexia\Apps\Acme\Workshop\Models\Example;
use Nexia\AsyncWork\AppWorkInvocation;
use Nexia\AsyncWork\Contracts\AppWorkHandler;
final class EnsureExample implements AppWorkHandler
{
public function handle(AppWorkInvocation $invocation): void
{
if ($invocation->key !== 'workshop.example.ensure' || $invocation->payload !== []) {
throw new InvalidArgumentException('Unexpected work payload.');
}
Example::firstOrCreate(
['public_id' => '018d4f35-84ed-4ce4-a421-277f7d872601'],
['name' => 'Background example'],
);
}
}src/Contribution/WorkshopWork.php를 추가합니다. 생성된 Manifest가 이 경로를 발견합니다:
<?php
declare(strict_types=1);
namespace Nexia\Apps\Acme\Workshop\Contribution;
use Nexia\Apps\Acme\Workshop\Work\EnsureExample;
use Nexia\AsyncWork\AppWorkDefinition;
use Nexia\AsyncWork\Contracts\AppWorkContribution;
final class WorkshopWork implements AppWorkContribution
{
public static function appWork(): array
{
return [new AppWorkDefinition('workshop.example.ensure', EnsureExample::class)];
}
}실행 요청
생성된 인증 Route·Controller 안에 POST 동작을 추가하고 아래 본문을 사용하세요. Request 검증과 리소스 Policy를 유지하며 요청자가 작업 키나 handler 클래스를 고르게 하지 않습니다. 이 예제는 의도적으로 빈 payload를 사용합니다:
use Nexia\AsyncWork\Contracts\AppWorkDispatcher;
$this->authorize('create', \Nexia\Apps\Acme\Workshop\Models\Example::class);
app(AppWorkDispatcher::class)->dispatch(
'workshop.example.ensure',
[],
'workshop.example.ensure.initial',
);
return response()->json(['accepted' => true], 202);고정된 멱등 키는 한 번의 초기화 요청을 뜻합니다. 실제 업무에서는 작업 식별자를 저장하고 동일 작업의 재시도에 재사용하세요. 새로운 업무에는 새로운 키가 필요합니다. 작업 자체는 여러 번 실행될 수 있으므로 handler도 중복 효과를 막아야 합니다. 이 예제는 고유 레코드 식별자를 사용합니다.
샌드박스 dispatcher를 앱 트랜잭션 안에서 호출하면 커밋 이후 전송합니다. 트랜잭션 outbox는 아니므로 커밋과 enqueue 사이 실패에 대비해 앱 작업 기록을 보관하고 같은 키로 재시도해야 합니다. enqueue 성공만으로 업무 완료를 표시하지 마세요.
필요한 경우에만 예약 추가
같은 contribution에 인터페이스와 메서드를 추가합니다. 실행 대상 설치와 트리거는 Core가 관리하고 앱은 5개 필드 cron 표현식과 제한된 payload를 선언합니다:
use Nexia\AsyncWork\AppWorkSchedule;
use Nexia\AsyncWork\Contracts\AppWorkScheduleContribution;
// Also implement AppWorkScheduleContribution on WorkshopWork.
public static function appWorkSchedules(): array
{
return [new AppWorkSchedule(
key: 'workshop.example.hourly',
workKey: 'workshop.example.ensure',
cron: '0 * * * *',
)];
}예약 작업에는 앱을 설치한 사용자의 권한이 자동으로 주어지지 않습니다. 사용자 권한이나 조직 검증을 건너뛰지 마세요. AppWorkInvocation은 executionId·key·attempt·payload를 전달하며 사용자·법인 DTO가 아닙니다. 업무별 권한 근거와 대상을 명시적으로 해석해야 합니다. 플랫폼 callback은 AppWorkDefinition.platformCallbacks에 선언하며 임의 이름을 넣는다고 권한이 부여되지 않습니다.
예약 핸들러에서도 기존 AppWorkDispatcher::dispatch()로 같은 앱에 선언된 후속 작업을 등록할 수 있습니다. 후속 등록에 별도 platformCallbacks 선언이나 시스템 사용자 생성은 필요하지 않습니다. 플랫폼이 실행 중인 작업의 유효성과 실행 범위를 확인하며, 후속 작업은 원래 실행의 소스와 사용자 없는 상태를 이어받습니다. 사용자 권한이 필요한 다른 콜백의 권한을 자동으로 얻지는 않습니다. 이 동작에는 대응하는 Core와 Manager/runtime 수정이 함께 적용돼야 합니다. 관련 이슈
플랫폼이 작업 종류와 앱별로 실행 기회를 나누므로 앱에서 큐나 우선순위를 선택할 필요는 없습니다. 각 작업 종류 안에서는 같은 앱의 작업을 등록 순서대로 선택합니다. 같은 앱의 작업은 순차 실행될 수 있으므로 긴 처리는 제한된 묶음으로 나누고 진행 위치를 저장하세요. 작업이 중단되거나 결과를 확인할 수 없는 경우에도 중복 반영하지 않도록 처리해야 합니다. 등록이나 예약 시각은 완료 시각을 보장하지 않습니다.
테넌트별 예약 작업
선택 기능의 AppWorkSchedule에 tenantManaged: true를 지정합니다. 테넌트 설정을 바꾸는 트랜잭션 안에서 EventPublisher로 AppWorkSchedule::activationChanged($scheduleKey, $enabled, $revision)을 발행합니다. 상태를 변경할 때마다 해당 스케줄의 리비전을 증가시키고, 같은 변경을 재전송할 때는 기존 값을 유지합니다. 기존 설치 상태를 처음 확인하는 예약 작업도 기능이 꺼져 있으면 비활성 상태를 발행합니다. Core가 이를 수신하면 이후 작업 배정을 중단합니다. 이미 접수된 작업은 앱 설정을 다시 확인해야 합니다. Core와 앱 런타임에 호환 PHP SDK를 적용하고 Core 테넌트 마이그레이션을 완료한 뒤 사용합니다.
독립 작업을 동시에 실행하기
기존 앱은 수정할 필요가 없습니다. 충돌 여부가 불확실하면 workConflictGroup을 생략하세요. 생략한 쓰기 작업은 같은 앱의 다른 쓰기 작업이 끝날 때까지 기다립니다.
예를 들어 앱의 기존 SyncPrices 핸들러는 상품 가격만 갱신하고 RenderBadges는 배지 이미지 파일만 생성한다고 가정합니다. 두 작업이 상대의 변경 결과에도 의존하지 않는지 확인한 뒤, 호환 PHP SDK에서 appWork()의 반환값에 다음과 같이 선언하세요.
return [
new AppWorkDefinition('workshop.prices.sync', SyncPrices::class, workConflictGroup: 'prices'),
new AppWorkDefinition('workshop.badges.render', RenderBadges::class, workConflictGroup: 'badges'),
];두 핸들러가 같은 급여 스냅샷을 갱신한다면 같은 그룹을 지정하거나 선언을 생략하세요. DB와 파일 변경, 호스트 콜백, 외부 요청, 재시도와 후속 작업의 영향까지 확인하세요. 후속 작업은 자체 선언에 따라 배정됩니다. 같은 설치 릴리스 안에서 그룹이 서로 다르면 가용 워커에서 동시에 실행될 수 있습니다. 그룹은 실행 순서만 정합니다. 같은 업무 요청을 재시도할 때는 원래 멱등 키를 사용하고, 핸들러가 다시 실행돼도 중복 저장되지 않도록 구현하세요. 가져오기 파이프라인 선언.
실행·복구 확인
- 프로젝트
nexia dev로 동기화하고 준비 완료를 기다립니다. Example 생성·조회 권한을 부여합니다. - 보호된 POST를 호출하고 Examples 목록에 레코드가 나타나는지 확인합니다.
202는 접수만 뜻합니다. - 같은 요청과 격리된 테스트의 handler 전달을 반복합니다. 레코드는 하나이고 수정한 이름도 유지돼야 합니다.
- 권한 없는 호출·잘못된 payload·handler 실패를 확인합니다. 실패한 업무를 성공으로 처리하지 않습니다.
- 예약 작업은 런타임 사용 중 실행 시각이 지나 실제 처리됐는지 확인합니다. 선언 등록만으로 관리형 scheduler 실행을 증명할 수 없습니다. 실행되지 않으면 작업 식별자로 지원 요청하세요.
커밋된 업무 이벤트에 반응하는 경우에는 이벤트와 비동기 작업을 사용합니다.
예약 핸들러는 Core가 선택한 현재 테넌트만 처리해야 합니다. 별도의 운영자 명령에서 TenantRunner::runForAll()로 순회한다면 각 콜백 안에서 먼저 app(InstalledApps::class)->isOperational('workshop')를 확인하고, false인 테넌트는 건너뛰세요. InstalledApps는 Nexia\AppRuntime\Contracts\InstalledApps입니다. App Schema 조회도 앱 DB 연결을 사용하므로 hasTable()은 설치 여부 확인을 대신할 수 없습니다. 설치된 앱에서 발생하는 실제 DB 오류를 숨기거나 Core DB 연결로 우회하지 마세요.
CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.