#APIResource

URL을 기반으로 요청을 보내는 범용 API 리소스로, 모든 HTTP 인터페이스에 적합합니다. FlowResource 기본 클래스를 상속받으며, 요청 설정과 refresh() 기능이 확장되었습니다. MultiRecordResource 및 SingleRecordResource와 달리 APIResource는 리소스 이름에 의존하지 않고 URL로 직접 요청하므로, 커스텀 인터페이스나 서드파티 API 등의 시나리오에 적합합니다.

생성 방식: ctx.makeResource('APIResource') 또는 ctx.initResource('APIResource'). 사용 전 setURL()을 설정해야 합니다. RunJS 컨텍스트에서는 ctx.api(APIClient)가 자동으로 주입되므로 setAPIClient를 수동으로 호출할 필요가 없습니다.

#적용 시나리오

#기본 클래스 기능 (FlowResource)

모든 리소스는 다음 기능을 갖추고 있습니다:

#요청 설정

#URL 형식

• 리소스 스타일: users:list, posts:get과 같은 NocoBase 리소스 약칭을 지원하며, baseURL과 결합됩니다.
• 상대 경로: /api/custom/endpoint와 같이 애플리케이션의 baseURL과 결합됩니다.
• 전체 URL: 교차 도메인 요청 시 전체 주소를 사용하며, 대상 서버에 CORS 설정이 되어 있어야 합니다.

#데이터 가져오기

#예시

#기본 GET 요청

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/endpoint');
res.setRequestParameters({ page: 1, pageSize: 10 });
await res.refresh();
const data = res.getData();

#리소스 스타일 URL

const res = ctx.makeResource('APIResource');
res.setURL('users:list');
res.setRequestParameters({ pageSize: 20, sort: ['-createdAt'] });
await res.refresh();
const rows = res.getData()?.data ?? [];

#POST 요청 (요청 본문 포함)

const res = ctx.makeResource('APIResource');
res.setURL('/api/custom/submit');
res.setRequestMethod('post');
res.setRequestBody({ name: '테스트', type: 'report' });
await res.refresh();
const result = res.getData();

#refresh 이벤트 리스닝

const res = ctx.makeResource('APIResource');
res.setURL('/api/stats');
res.on('refresh', () => {
  const data = res.getData();
  ctx.render(<div>통계: {JSON.stringify(data)}</div>);
});
await res.refresh();

#에러 처리

const res = ctx.makeResource('APIResource');
res.setURL('/api/may-fail');
try {
  await res.refresh();
  const data = res.getData();
} catch (e) {
  const err = res.getError();
  ctx.message.error(err?.message ?? '요청 실패');
}

#사용자 정의 요청 헤더

const res = ctx.makeResource('APIResource');
res.setURL('https://api.example.com/data');
res.addRequestHeader('X-Custom-Header', 'value');
res.addRequestParameter('key', 'xxx');
await res.refresh();

#주의사항

• ctx.api 의존성: RunJS에서 ctx.api는 실행 환경에 의해 주입되므로 보통 수동으로 setAPIClient를 호출할 필요가 없습니다. 컨텍스트가 없는 환경에서 사용할 경우 직접 설정해야 합니다.
• refresh는 곧 요청: refresh()는 호출 시점의 설정을 바탕으로 요청을 실행합니다. 메서드, 파라미터, 데이터 등은 호출 전에 미리 설정되어야 합니다.
• 에러 시 데이터 미갱신: 요청 실패 시 getData()는 이전 값을 유지하며, getError()를 통해 에러 정보를 확인할 수 있습니다.
• ctx.request와의 차이: 단순 일회성 요청은 ctx.request()를 사용하고, 반응형 데이터, 이벤트, 에러 상태 관리가 필요한 경우 APIResource를 사용하십시오.

#관련 문서

• ctx.resource - 현재 컨텍스트의 리소스 인스턴스
• ctx.initResource() - 리소스 초기화 및 ctx.resource에 바인딩
• ctx.makeResource() - 바인딩 없이 새 리소스 인스턴스 생성
• ctx.request() - 단순 일회성 호출에 적합한 범용 HTTP 요청
• MultiRecordResource - 컬렉션/목록 대상, CRUD 및 페이지네이션 지원
• SingleRecordResource - 단일 레코드 대상