Laravel API 유지보수 패턴 가이드: 외주 인수 후 컨트롤러·서비스·마이그레이션 기준
직접 답부터 말하면, Laravel API 유지보수의 핵심은 ‘멋진 아키텍처’를 도입하는 것이 아니라 기능을 고칠 때 어디를 봐야 하는지 팀 안에서 예측 가능하게 만드는 것입니다. 외주 개발로 MVP를 빠르게 만들었거나 SaaS API를 인수하는 상황이라면 우선순위는 명확합니다. 컨트롤러는 HTTP 입출력 조율만 맡기고, 검증은 FormRequest, 응답 형태는 Resource, 권한은 Policy 또는 Gate, 비즈니스 흐름은 Action 또는 Service, DB 변경은 append-only 마이그레이션 규약, 핵심 시나리오는 Feature 테스트로 고정해야 합니다.
좋은 Laravel API는 폴더가 많아서 좋은 것이 아닙니다. 신규 개발자가 들어왔을 때 ‘이 기능은 Controller가 아니라 StoreOrderAction과 OrderResource를 보면 된다’고 설명할 수 있어야 합니다.
왜 지금 Laravel API 유지보수 패턴을 다시 봐야 하나
Laravel 12는 공식 릴리스 노트에서 Laravel 11.x의 개선을 이어가며 upstream dependency를 업데이트하는 성격이 강한 maintenance release로 설명됩니다. 동시에 공식 지원 정책상 Laravel 12의 버그 수정 종료일은 2026년 8월 13일, 보안 수정 종료일은 2027년 2월 24일로 안내되어 있습니다. Laravel 13은 2026년 3월 17일 릴리스되었고 PHP 8.3 이상을 요구합니다. 즉, 2026년 8월 중순 이후 Laravel 12 프로젝트를 인수하는 팀은 ‘당장 돌아가는가’뿐 아니라 ‘13으로 올릴 준비가 되어 있는가’를 함께 봐야 합니다.
이 지점에서 비개발 의사결정자가 자주 놓치는 부분이 있습니다. 프레임워크 버전만 확인하면 충분하다고 생각하지만 실제 업그레이드 리스크는 PHP 런타임, Composer 패키지, Carbon 같은 날짜 처리 의존성, PHPUnit 또는 Pest 테스트 버전, CI 설정, 운영 서버 확장 모듈에서 동시에 발생합니다. Laravel 12 업그레이드 문서에는 Carbon 3.x 요구와 테스트 도구 의존성 변경이 명시되어 있고, Laravel 13 문서에서는 PHP 8.3 이상이 요구됩니다. 외주 인수 검수에서 이 항목을 빼면 나중에 간단한 기능 수정도 서버 교체나 패키지 충돌 문제로 번질 수 있습니다.
| 점검 항목 | 왜 중요한가 | 인수 시 확인 질문 |
|---|---|---|
| Laravel 버전 | 지원 종료 시점과 업그레이드 경로가 달라짐 | 현재 11, 12, 13 중 무엇이며 composer.json 제약은 어떻게 되어 있는가 |
| PHP 런타임 | 로컬, CI, 운영이 다르면 재현 불가능한 버그가 생김 | Docker, 서버, CI가 같은 PHP minor 버전을 쓰는가 |
| Composer 패키지 | 버려진 패키지나 고정 버전이 업그레이드를 막음 | composer.lock이 커밋되어 있고 보안 업데이트 정책이 있는가 |
| 테스트 | 업그레이드 전후 동작 차이를 판단할 기준이 됨 | 핵심 API Feature 테스트가 최소한 존재하는가 |
| 마이그레이션 | DB 이력 혼선은 장애와 데이터 손실로 직결됨 | 운영 반영된 마이그레이션을 수정하지 않는 규칙이 있는가 |
외주 인수 시 1차로 봐야 할 5가지 유지보수 리스크
Laravel 프로젝트는 빠르게 만들기 좋기 때문에 MVP에는 강점이 있습니다. 하지만 빠른 개발의 흔적이 운영 리스크로 남는 경우도 많습니다. 다음 표는 개발자가 아닌 창업자, PM, 정부지원사업 과제 책임자도 외주 결과물을 검수할 때 사용할 수 있는 1차 진단 기준입니다.
| 리스크 | 위험 신호 | 유지보수 영향 | 권장 대응 |
|---|---|---|---|
| 컨트롤러 비대화 | Controller 한 메서드에서 검증, 권한, 결제, DB 저장, 알림 발송을 모두 처리 | 기능 하나를 고치다 다른 API가 깨질 가능성이 커짐 | FormRequest, Policy, Action 또는 Service, Job으로 책임 분리 |
| 서비스 계층 부재 | 비즈니스 규칙이 여러 컨트롤러에 복사되어 있음 | 요금제, 상태값, 권한 규칙 변경 때 중복 수정 발생 | 업무 흐름 단위의 Action을 먼저 만들고 반복 규칙만 Service로 묶기 |
| 마이그레이션 혼선 | 이미 실행된 migration 수정, 수동 SQL만 존재, down 메서드 없음 | 신규 개발자 환경 구성 실패, 운영 DB 변경 추적 불가 | 새 migration 추가 원칙, 상태 확인, schema dump, 백필 절차 정리 |
| 응답 계약 불안정 | Controller에서 Eloquent 모델을 그대로 반환하거나 필드명이 기능마다 다름 | 프론트엔드, 모바일 앱, 외부 파트너 연동이 자주 깨짐 | Http Resource로 응답 필드, meta, pagination 형식 고정 |
| 테스트 공백 | tests 디렉터리가 비어 있거나 예제 테스트만 있음 | 업그레이드와 리팩터링을 감으로 진행하게 됨 | 로그인, 권한, 결제, 관리자 CRUD, webhook부터 Feature 테스트 작성 |
유지보수 가능한 Laravel API의 최소 폴더 구조
MVP나 초기 SaaS에서 처음부터 DDD, CQRS, 클린 아키텍처를 전면 도입할 필요는 없습니다. 오히려 작은 팀은 구조가 과해지면 개발 속도와 이해도가 떨어집니다. 현실적인 기준은 Laravel 기본 구조를 존중하되, HTTP 책임과 비즈니스 책임이 섞이지 않도록 얇은 계층을 추가하는 것입니다.
app/
Http/
Controllers/Api/V1/
Requests/Orders/
Resources/Orders/
Actions/
Orders/
Services/
Billing/
Notification/
Policies/
Models/
Jobs/
Exceptions/
database/
migrations/
seeders/
tests/
Feature/Api/
Unit/권장 흐름은 단순합니다. Route는 URI와 middleware를 연결하고, Controller는 요청을 받아 Action 또는 Service를 호출합니다. FormRequest는 입력 검증과 요청 단위 권한을 담당하고, Policy는 모델 중심 권한을 담당합니다. Action 또는 Service는 트랜잭션과 업무 규칙을 처리하고, Resource는 응답 JSON을 안정적인 계약으로 변환합니다. 이 흐름이 정리되면 API 문서가 조금 부족해도 코드 자체가 업무 흐름을 설명하게 됩니다.
컨트롤러 기준: HTTP 조율자 이상을 맡기지 않는다
컨트롤러가 커지는 이유는 대부분 일정 압박 때문입니다. 처음에는 저장 하나만 하다가, 권한 체크, 파일 업로드, 외부 API 호출, 알림 발송, 상태 변경 로그가 차례로 붙습니다. 이 상태에서 새 개발자가 들어오면 어떤 변경이 안전한지 판단하기 어렵습니다.
| 컨트롤러에 남겨도 되는 것 | 빼야 하는 것 | 이동 위치 |
|---|---|---|
| Route model binding으로 받은 모델 전달 | 복잡한 입력 검증 배열 | FormRequest |
| Action 호출과 Resource 반환 | 여러 테이블을 함께 바꾸는 트랜잭션 | Action 또는 Service |
| HTTP status code 결정 | 요금제, 쿠폰, 정산 같은 업무 규칙 | Domain Service |
| 간단한 pagination 파라미터 전달 | 권한 조건을 if문으로 반복 작성 | Policy 또는 Gate |
| 예외를 그대로 framework handler에 전달 | 메일, 슬랙, 외부 webhook 즉시 실행 | Job 또는 Event Listener |
실무 기준으로는 컨트롤러 메서드 하나가 화면 한 페이지를 넘어가거나, if 분기가 세 개 이상 겹치거나, DB 저장 이후 외부 시스템 호출이 붙기 시작하면 분리 검토 시점으로 보는 것이 좋습니다. 숫자 자체가 법칙은 아니지만, 리뷰할 때 토론을 시작하는 기준으로는 유용합니다.
서비스 계층과 Action 계층을 어떻게 나눌까
Laravel 커뮤니티에서도 Service Layer를 어디까지 둘지는 팀마다 다릅니다. 중요한 것은 이름이 아니라 변경 단위입니다. MVP에서는 모든 기능에 Service를 만들기보다 ‘하나의 사용자 의도’를 Action으로 분리하는 접근이 더 실용적일 때가 많습니다.
| 패턴 | 적합한 경우 | 예시 | 주의점 |
|---|---|---|---|
| Action | 하나의 API 요청 또는 업무 유스케이스를 처리 | CreateSubscriptionAction, ApproveProjectAction | Action이 커지면 내부 규칙을 Service로 다시 분리 |
| Service | 여러 Action에서 공유하는 도메인 규칙 또는 외부 연동 | BillingService, SmsService, FileScanService | 모든 Model별로 기계적으로 만들면 빈 껍데기만 늘어남 |
| Policy | 사용자가 특정 리소스에 대해 할 수 있는지 판단 | ProjectPolicy update, delete | 비즈니스 계산까지 넣지 말고 권한 판단에 집중 |
| Job | 응답을 늦출 필요 없는 후속 처리 | SendInvoiceMail, SyncCrmContact | 재시도와 실패 로그 기준을 함께 정해야 함 |
| Repository | 쿼리 복잡도가 높거나 저장소 교체 가능성이 실제로 있음 | 복잡한 검색, 리포트 쿼리 | Eloquent를 감추기 위해 무조건 만들 필요는 없음 |
작은 SaaS에서는 Controller → Action → Eloquent 정도로 충분한 경우가 많습니다. 다만 과금, 권한, 정산, 재고, 승인 workflow처럼 실수 비용이 큰 영역은 초기에 Service를 두는 편이 안전합니다. 특히 정부지원사업 MVP라도 최종 데모 이후 실제 고객 데이터가 들어갈 계획이라면 결제, 관리자 승인, 파일 업로드, 알림 발송은 반드시 책임을 분리해 두는 편이 좋습니다.
요청과 응답 계약: FormRequest와 Resource를 기본값으로 둔다
Laravel 공식 문서에서 FormRequest는 app/Http/Requests 아래 생성되며 authorize와 rules 메서드를 가집니다. API 요청이 XHR 또는 JSON 기대 요청인 경우 validation 실패 시 422 상태 코드와 JSON 형태의 오류 응답을 받을 수 있습니다. 이 특성은 프론트엔드와 백엔드가 명확한 입력 계약을 공유하게 해 줍니다.
실무에서는 FormRequest를 단순 검증 파일로만 보지 말고 다음 네 가지를 고정하는 장소로 활용합니다.
- 입력 필드의 허용 범위: nullable, required, enum, array dot notation을 명확히 한다.
- 요청 단위 권한: 본인이 소유한 리소스인지, 특정 역할만 가능한지 authorize에서 판단한다.
- 정규화: 전화번호, 날짜, boolean 값처럼 프론트 입력이 흔들리는 필드는 저장 전 형태를 맞춘다.
- 테스트 기준: 유효하지 않은 입력에 대해 422와 오류 키가 일관되게 나오는지 Feature 테스트로 잠근다.
응답은 Eloquent 모델을 그대로 반환하지 않는 편이 좋습니다. Laravel API Resource는 Eloquent 모델과 실제 JSON 응답 사이에 변환 계층을 제공합니다. 이 계층을 두면 내부 컬럼명이 바뀌어도 외부 응답 계약을 유지할 수 있고, 관리자 화면용 응답과 고객 앱용 응답을 구분하기도 쉬워집니다.
| 상황 | 나쁜 응답 방식 | 권장 방식 |
|---|---|---|
| 사용자 정보 반환 | User 모델 전체 반환 | UserResource에서 공개 필드만 반환 |
| 목록 pagination | 각 컨트롤러마다 meta 형식이 다름 | ResourceCollection 또는 공통 pagination meta 사용 |
| 권한별 필드 노출 | 프론트에서 숨김 처리 | Resource에서 요청 사용자 권한에 따라 필드 제어 |
| 외부 파트너 API | DB 컬럼명을 그대로 노출 | 버전이 있는 명시적 응답 스키마로 고정 |
마이그레이션 규약: DB 변경은 코드보다 더 보수적으로 다룬다
Laravel 공식 문서는 migration을 데이터베이스를 위한 version control로 설명합니다. 파일명에 timestamp가 붙어 실행 순서를 결정하고, schema dump를 통해 누적된 migration을 정리할 수도 있습니다. 이 기본 철학을 외주 인수 기준으로 바꾸면 다음 원칙이 됩니다.
- 운영 또는 공유 DB에 적용된 migration은 수정하지 않는다. 변경이 필요하면 새 migration을 추가한다.
- 파괴적 변경은 한 번에 하지 않는다. 컬럼 추가, 데이터 백필, 코드 전환, 제약 강화, 기존 컬럼 제거 순서로 나눈다.
- 수동 SQL은 기록 없이 실행하지 않는다. 부득이하게 실행했다면 같은 효과를 내는 migration 또는 운영 이력 문서를 남긴다.
- 배포 전 SQL을 확인한다. 중요한 변경은 migrate --pretend로 SQL을 검토하고, 여러 서버 배포 환경에서는 migrate --isolated 같은 중복 실행 방지 옵션을 검토한다.
- down 메서드만 믿지 않는다. 운영 롤백은 DB 백업, forward fix, feature flag, 읽기 전용 전환 계획까지 함께 봐야 한다.
마이그레이션이 이미 복잡하게 꼬인 프로젝트라면 먼저 migration 파일을 모두 고치려 하지 말고 현재 운영 DB 스키마, migration 실행 상태, 로컬 재현 가능성을 분리해 봐야 합니다. 운영 중 스키마 변경과 백필 절차는 데이터베이스 마이그레이션 전략 가이드에서 더 자세히 다룬 기준을 함께 참고하면 좋습니다.
테스트 기준: 처음부터 전체 커버리지를 목표로 잡지 않는다
Laravel은 기본적으로 Unit과 Feature 테스트 구조를 제공합니다. 공식 문서에서도 Feature 테스트는 여러 객체의 상호작용이나 JSON endpoint에 대한 전체 HTTP 요청을 검증할 수 있다고 설명합니다. 외주 인수 프로젝트에서는 이 장점을 이용해 가장 비싼 장애부터 잠가야 합니다.
| 우선순위 | 테스트 대상 | 검증할 것 | 이유 |
|---|---|---|---|
| 1 | 인증·권한 | 비로그인, 일반 사용자, 관리자 접근 차이 | 보안 사고와 데이터 노출을 막음 |
| 2 | 핵심 CRUD | 생성, 수정, 삭제, 소유자 제한, validation 오류 | 관리자 화면과 고객 기능의 기본 안정성 확보 |
| 3 | 결제·구독·정산 | 중복 결제 방지, 상태 전이, webhook 재처리 | 금전 관련 오류는 복구 비용이 큼 |
| 4 | 외부 연동 | 실패 응답, timeout, 재시도, 로그 | 외부 API 장애가 내부 장애로 전파되는 것을 줄임 |
| 5 | 리포트·검색 | 필터, 정렬, pagination, 권한별 결과 | SaaS 운영 화면에서 문의가 자주 발생함 |
테스트가 아예 없다면 리팩터링보다 먼저 Golden Path Feature 테스트를 작성하는 것이 낫습니다. 예를 들어 회원가입 후 프로젝트 생성, 관리자 승인, 알림 발송 큐 적재까지 한 흐름을 테스트로 묶으면 이후 컨트롤러 분리나 서비스 계층 도입을 훨씬 안전하게 진행할 수 있습니다. 외주 결과물 검수와 테스트 범위를 산정할 때는 외주개발 테스트 자동화 가이드의 QA 범위 기준을 함께 보면 일정과 비용 논의가 구체화됩니다.
Laravel 12·13 업그레이드 리스크 체크리스트
Laravel 업그레이드는 공식 문서상 짧은 예상 시간이 표시될 수 있지만, 실제 프로젝트의 난이도는 커스텀 코드와 패키지 상태에 좌우됩니다. 특히 외주 인수 프로젝트는 기존 개발자의 암묵지가 빠져 있기 때문에 문서상 예상 시간만 보고 계약 범위를 잡으면 위험합니다.
| 영역 | 확인할 것 | 문제가 있으면 |
|---|---|---|
| PHP | Laravel 12는 PHP 8.2 이상 범위, Laravel 13은 PHP 8.3 이상 요구 | 서버, Docker, CI 런타임을 먼저 맞춘 뒤 업그레이드 |
| Composer | laravel/framework, tinker, phpunit, pest 등 버전 제약 | 별도 브랜치에서 composer update 후 충돌 패키지 목록화 |
| Carbon | Laravel 12에서 Carbon 3.x 요구 | 날짜 비교, timezone, diff 계산 테스트 추가 |
| 테스트 | Feature 테스트가 핵심 API를 커버하는지 | 업그레이드 전 현재 동작을 먼저 테스트로 고정 |
| 운영 설정 | config cache, route cache, queue worker, scheduler | 배포 스크립트와 재시작 절차를 문서화 |
| 패키지 | abandoned package, 오래된 helper, custom macro | 대체 패키지 또는 제거 계획 수립 |
업그레이드는 구조 정비와 섞어서 한 번에 끝내려 하면 원인 추적이 어려워집니다. 권장 순서는 현재 버전에서 테스트를 먼저 만들고, 컨트롤러 비대화 중 장애 위험이 큰 부분만 분리한 뒤, 별도 브랜치에서 의존성 업데이트와 프레임워크 업그레이드를 검증하는 것입니다.
외주 인수 후 2주 정비 로드맵
인수 직후 모든 코드를 리팩터링하겠다는 계획은 대부분 실패합니다. 더 현실적인 목표는 2주 안에 ‘어디가 위험한지’, ‘어디부터 고칠지’, ‘배포 전 무엇을 확인할지’를 팀 기준으로 고정하는 것입니다.
| 기간 | 목표 | 주요 작업 | 산출물 |
|---|---|---|---|
| 1~2일차 | 기술 현황 파악 | 버전, PHP, Composer, route, controller, migration, tests 스캔 | 인수 진단표, 위험도 목록 |
| 3~5일차 | API 계약 고정 | 핵심 endpoint의 request, response, error format 문서화 | API 계약표, Resource 분리 후보 |
| 6~8일차 | 테스트 안전망 구축 | 로그인, 관리자 권한, 핵심 CRUD, 결제 또는 webhook Feature 테스트 작성 | php artisan test 기준선, CI 실행 결과 |
| 9~11일차 | 고위험 리팩터링 | 비대한 Controller 1~2개를 Action 또는 Service로 분리 | 리팩터링 PR, 변경 전후 테스트 결과 |
| 12~14일차 | 운영·업그레이드 계획 | migration 규약, 배포 체크리스트, Laravel 13 영향도 검토 | 유지보수 백로그, 업그레이드 의사결정 자료 |
배포 전 체크리스트: Laravel API 운영에서 자주 빠지는 항목
- composer.lock이 저장소에 포함되어 있고 운영 배포가 동일한 lock 파일을 사용하는가
- 로컬, CI, staging, production의 PHP 버전과 extension 목록이 일치하는가
- .env 값 중 APP_DEBUG, APP_ENV, queue, mail, storage, cache 설정이 운영 기준으로 분리되어 있는가
- 마이그레이션 실행 전 백업 또는 snapshot, migrate --pretend 검토, 롤백 또는 forward fix 기준이 있는가
- queue worker와 scheduler가 배포 후 재시작되는가
- 관리자 API와 고객 API의 권한 middleware가 route group 단위로 분리되어 있는가
- FormRequest validation 실패, 권한 실패, 서버 오류의 JSON 형식이 일관되는가
- 외부 API timeout, retry, 실패 로그, 관리자 재처리 화면이 있는가
- 핵심 Feature 테스트가 CI에서 자동 실행되고 실패 시 배포가 멈추는가
- 장애 대응 시간, 버그 수정 범위, 서버 운영 책임이 유지보수 계약에 분리되어 있는가
마지막 항목은 기술 문제가 아니라 운영 계약 문제입니다. 외주 개발 이후 장애 대응과 버그 수정 범위가 불분명하면 Laravel 구조가 좋아도 책임 공백이 생깁니다. 유지보수 범위와 응답 기준은 외주개발 유지보수 SLA 설계 가이드처럼 별도 문서로 합의하는 편이 안전합니다.
AgentMit 관점: 작은 팀에는 과한 설계보다 인수 가능한 설계가 먼저다
AgentMit가 Laravel 기반 MVP, SaaS API, 관리자 대시보드, 업무 자동화 프로젝트를 볼 때 가장 먼저 확인하는 것도 고급 패턴의 유무가 아닙니다. 새 기능을 추가할 때 수정 위치가 예측 가능한지, DB 변경을 추적할 수 있는지, 핵심 API를 테스트로 보호할 수 있는지, 운영자가 문제를 재현할 수 있는지가 먼저입니다.
BizMit처럼 관리자 화면과 업무 운영 기능이 붙는 서비스에서는 API가 단순 CRUD에 머물지 않습니다. 승인, 반려, 권한 위임, 파일 검수, 알림, 통계, 외부 API 연동이 붙으면서 컨트롤러가 쉽게 비대해집니다. 이때 처음부터 거대한 아키텍처로 갈 필요는 없지만, Controller, FormRequest, Action, Service, Resource, Migration, Test의 최소 기준은 프로젝트 초기에 잡아야 합니다.
외주 개발 결과물을 인수했는데 구조 진단, 리팩터링 우선순위, 테스트·CI 자동화, 관리자 기능 개선, Laravel 12에서 13 업그레이드 영향도 검토가 필요하다면 AgentMit가 구현 파트너로 참여할 수 있습니다. 다만 이 글의 체크리스트만으로도 내부 개발자 또는 기존 외주사와 훨씬 구체적인 대화를 시작할 수 있을 것입니다. 상담이 필요하면 AgentMit 제작 문의에서 현재 저장소 상태와 운영 이슈를 기준으로 논의하면 됩니다.
FAQ
Q1. Laravel API에서 서비스 계층은 꼭 만들어야 하나요?
모든 CRUD에 무조건 서비스 클래스를 만들 필요는 없습니다. 다만 결제, 권한, 재고, 정산, 외부 API 연동처럼 트랜잭션과 예외 처리가 섞이는 기능은 Controller 밖의 Action 또는 Service로 분리하는 것이 유지보수에 유리합니다.
Q2. 외주 개발된 Laravel 프로젝트를 인수할 때 가장 먼저 확인할 파일은 무엇인가요?
composer.json, composer.lock, routes/api.php, app/Http/Controllers, app/Http/Requests, app/Http/Resources, database/migrations, tests 디렉터리를 먼저 봐야 합니다. 이 7곳만 봐도 버전 리스크, 컨트롤러 비대화, 검증 규칙, 응답 계약, DB 변경 이력, 테스트 공백을 빠르게 파악할 수 있습니다.
Q3. 이미 운영 DB에 적용된 Laravel 마이그레이션 파일을 수정해도 되나요?
공유 개발 DB나 운영 DB에 이미 적용된 마이그레이션은 수정하지 않는 것이 원칙입니다. 새 마이그레이션을 추가해 변경 이력을 남기고, 위험한 변경은 추가 컬럼 생성, 데이터 백필, 코드 전환, 기존 컬럼 제거 순서로 나누는 편이 안전합니다.
Q4. 테스트가 없는 Laravel API는 어디부터 테스트해야 하나요?
회원가입·로그인, 결제·구독, 관리자 권한, 핵심 데이터 생성·수정·삭제, 외부 webhook 같은 장애 비용이 큰 Feature 테스트부터 시작하는 것이 현실적입니다. 이후 순수 계산 로직이나 정책 판단은 Unit 테스트로 보강하면 됩니다.
Q5. Laravel 12 프로젝트를 바로 Laravel 13으로 올리는 것이 좋나요?
PHP 8.3 이상 운영 환경, Composer 패키지 호환성, Feature 테스트, 배포 롤백 경로가 준비되어 있다면 13 업그레이드를 검토할 수 있습니다. 준비가 부족하다면 먼저 테스트와 마이그레이션 규약을 정리한 뒤 별도 브랜치에서 업그레이드 영향도를 확인하는 순서가 안전합니다.
참고한 공식 문서
이 글은 외부 블로그의 의견보다 Laravel 공식 문서의 릴리스, 업그레이드, 컨트롤러, 검증, 리소스, 마이그레이션, 테스트, 배포 문서를 우선 참고했습니다. 프로젝트별 구조 판단은 위 문서를 그대로 적용하기보다 팀 규모, 운영 데이터, 배포 체계, 외주 인수 상황에 맞춰 조정해야 합니다.
- Laravel 13.x Release Notes — 지원 정책, 릴리스 정보, PHP 8.3 요구사항 확인
- Laravel 12.x Release Notes — Laravel 12 유지보수 성격과 지원 일정 확인
- Laravel 12.x Upgrade Guide — Carbon 3.x와 테스트 도구 의존성 변경 확인
- Laravel 13.x Upgrade Guide — 12에서 13으로 올릴 때의 의존성 변경 확인
- Laravel 13.x Controllers — apiResource와 컨트롤러 책임 기준 확인
- Laravel 13.x Validation — FormRequest와 422 JSON validation 응답 확인
- Laravel 13.x Eloquent API Resources — 모델과 JSON 응답 사이의 변환 계층 확인
- Laravel 13.x Migrations — migration, schema dump, 운영 실행 옵션 확인
- Laravel 13.x Testing — Unit과 Feature 테스트의 역할 확인
- Laravel 13.x Deployment — 운영 서버 요구사항 확인
