13.x, 프레임워크 구현은 최신 릴리스인 v13.34.0을 참조합니다.
loadRoutesFrom은 파일을 로드할 뿐
ServiceProvider::loadRoutesFrom()은 애플리케이션이 CachesRoutes를 구현하고 routesAreCached()가 참인 경우에는 라우트 파일을 로드하지 않습니다. 그 외의 경우에는 지정한 파일을 require합니다.
이 메서드 자체는 URI나 라우트 이름의 프리픽스, 컨트롤러 네임스페이스, 미들웨어를 추가하지 않습니다. 파일 배포나 기존 캐시에 라우트를 추가하는 일도 하지 않습니다.
그림은 표준 Laravel 애플리케이션을 전제로 합니다. 패키지 전용 캐시가 있는 것이 아니라, 애플리케이션 전체의 라우트 캐시에 패키지의 라우트도 포함됩니다.
설정과 등록을 분리하기
다음 예시에서는 패키지가 응답 가능한지를 반환하는 공개 엔드포인트를 만듭니다. Composer의 PSR-4로Acme\Courier\를 src/에 대응시키고, 프로바이더를 자동 감지 또는 수동으로 등록했다고 가정합니다.
config/courier.php
register(), 라우트 로드는 boot()에서 수행합니다. HTTP 라우트를 등록하는 프로바이더를 DeferrableProvider로 만들지 마세요. 라우트가 필요한 시점에 프로바이더가 부팅된다는 보장이 없어지기 때문입니다.
src/CourierServiceProvider.php
routes/web.php
src/Http/Controllers/StatusController.php
/acme-courier/status, 라우트 이름은 acme-courier.status입니다. route('acme-courier.status')로 URL을 생성하면 URI 프리픽스를 변경해도 호출하는 쪽은 같은 라우트 이름을 사용할 수 있습니다. 그룹의 name()은 문자열을 그대로 연결하므로 끝의 .도 지정합니다.
web은 인증·인가를 대신하지 않습니다. 이 예시는 기밀 정보를 포함하지 않는 공개 엔드포인트입니다. 사용자의 데이터를 반환하는 엔드포인트에는 사양에 맞는 인증 미들웨어와 인가 처리를 별도로 마련하세요.URI와 라우트 이름의 충돌을 따로 방지하기
URI 프리픽스와 라우트 이름 프리픽스는 별개의 구조입니다. 한쪽만 붙여서는 다른 쪽의 충돌을 막을 수 없습니다.AbstractRouteCollection은 캐시용 라우트 컬렉션을 만들 때 다른 라우트에 같은 이름이 붙어 있으면 LogicException을 던지는 처리를 가지고 있습니다. “일반 부팅에서 URL을 생성할 수 있었다”는 것만으로는 캐시 가능하다고 보장할 수 없습니다. URI가 다른 두 라우트라도 이름이 같으면 문제가 됩니다.
사용하는 애플리케이션의 라우트를 등록 순서로 덮어쓰는 것을 패키지의 확장 방법으로 삼지 마세요. 필요하다면 라우트를 비활성화하는 설정과, 사용자가 별도의 라우트에서 호출할 수 있는 서비스를 제공합니다.
캐시 생성 시의 설정이 라우트 정의에 남는다
RouteCacheCommand는 먼저 route:clear를 실행하고, 새 애플리케이션을 부팅하여 라우트를 수집합니다. 그 라우트를 직렬화할 수 있는 형태로 준비하고, 컴파일 결과를 캐시 파일에 기록합니다.
이때 패키지의 라우트 파일도 로드되므로, 프리픽스나 등록 여부는 캐시 생성 시의 설정으로 결정됩니다. 이후 부팅에서는 loadRoutesFrom()이 파일을 로드하지 않고 캐시된 라우트가 사용됩니다.
사용자나 테넌트 등 요청마다 바뀌는 조건으로 라우트를 등록하지 마세요. 그 조건은 캐시 생성 시의 CLI 환경에서 평가됩니다. 라우트는 안정적인 구성으로 등록하고, 접근 가능 여부는 미들웨어나 컨트롤러 내의 인가로 판단합니다.
배포에서는 설정을 먼저 확정하기
코드와 설정의 업데이트를 마친 뒤, 설정 캐시를 사용하는 구성에서는 다음 순서로 다시 생성합니다. 사용하는 애플리케이션의 배포 처리에 포함시키세요.route:cache를 실행하면 라우트도 오래된 설정으로 만들어집니다. config:cache만 다시 실행해도 라우트 캐시는 업데이트되지 않습니다. -vv로 미들웨어 그룹의 내용도 확인할 수 있습니다.
개발 중에 캐시 없이 동작을 확인하는 경우에는 필요에 따라 둘 다 지웁니다.
릴리스 전에 확인할 조합
패키지 테스트에 더해, Laravel 13을 사용하는 애플리케이션에서 다음 조합을 확인합니다. 인메모리 라우트 등록뿐 아니라 Artisan이 새 애플리케이션을 부팅하는 경로도 대상으로 합니다.- 캐시 없이
/acme-courier/status가 응답하고, 라우트 이름과 미들웨어가 예상대로이다. route:cache가 성공하고, 새로운 부팅에서도 같은 URI·라우트 이름으로 응답한다.- 프리픽스를 변경하고 캐시를 다시 생성하면 새 URI가 응답하고, 이전 URI의 패키지 라우트가 사라진다.
- 비활성화하고 캐시를 다시 생성하면
route:list --name=acme-courier에 대상 라우트가 나오지 않는다. - 사용하는 애플리케이션이나 다른 패키지와 URI·라우트 이름이 충돌하지 않는다.
관련 페이지
라우팅
라우트 그룹, 이름 있는 라우트, 목록 표시의 기본을 확인합니다.
패키지 설정 병합과 캐시
배포된 설정과 설정 캐시를 고려한 업데이트 절차를 확인합니다.
지연 서비스 프로바이더
라우트를 등록하는 프로바이더를 지연시키지 않는 이유를 확인합니다.
패키지의 버전 호환성 관리
공개 API의 변경을 릴리스 방침과 지속적인 검증에 연결합니다.