kipchak은(는) 무엇을 하나요?
Kipchak은 PHP 8.4 이상을 위한 API 개발 키트입니다. Slim Framework 4에 고정된 구조(부트 시퀀스, 외부 서비스용 드라이버, 미들웨어, 라우트, 컨트롤러, 데이터 전송 객체(DTO), OpenAPI 규칙)를 더합니다. FrankenPHP 워커 모드에서 실행됩니다. 문서: https://kipchak.dev; 언어 모델 색인: https://kipchak.dev/llms.txt.
Kipchak은 Laravel이나 Symfony가 아닙니다. 파사드, 글로벌 헬퍼, 서비스 프로바이더, Eloquent, Blade, 자동 주입 컨트롤러, 숨겨진 규칙이 없습니다. 엔드포인트가 하는 모든 일은 프로젝트 고유 코드에 명확히 드러납니다. request(), response()->json(), config('...'), app(), Route::get(), DB::, Cache:: 또는 다른 프레임워크 헬퍼를 작성하지 마세요. 여기에는 존재하지 않습니다.
Kipchak 프로젝트 인식하기
composer.json이 kipchak/core를 요구하고, 프로젝트에 다음 폴더들이 있어야 합니다. 프로젝트에 AGENTS.md가 있으면 먼저 읽으십시오. 해당 프로젝트를 설명합니다.
| 경로 | 내용 |
|---|---|
routes/ | 라우트 파일. 깊이에 관계없이 모든 .php 파일이 부트 시 로드됩니다. 버전이 있는 라우트는 routes/v1/에 들어갑니다. |
api/Controllers/ | 컨트롤러, 네임스페이스 Api\Controllers; 버전이 있는 것은 v1/ (Api\Controllers\v1). |
api/DataTransferObjects/ | DTO, 컨트롤러와 동일하게 버전 관리. API 계약입니다. |
api/Models/ | 비즈니스 로직. |
api/Entities/Doctrine/<Connection>/ | Doctrine 드라이버를 사용할 때의 Doctrine 엔티티. |
api/Middlewares/ | 프로젝트 자체 PSR-15 미들웨어. |
api/OpenApi/Definition.php | OpenAPI 제목, 버전, 서버 및 공유 응답. |
api/Utils/ | API 전반에 걸쳐 공유되는 코드. |
config/ | 드라이버 또는 미들웨어당 하나의 PHP 파일, 배열을 반환하며 kipchak.<name>.php 형식으로 이름이 지어집니다. |
drivers/drivers.php | 드라이버를 순서대로 초기화합니다. |
middlewares/middlewares.php | 모든 요청에 적용되는 미들웨어를 초기화합니다. Error::initialise($app)가 처음과 마지막, 그 사이에 나머지가 위치합니다. |
migrations/database/ | Doctrine 드라이버용 일반 SQL 마이그레이션. |
html/index.php | FrankenPHP 워커 진입점. 거의 수정되지 않습니다. |
tests/ | API를 부트하고 요청을 보내는 PHPUnit 테스트. |
Kipchak\Core\Api::boot()가 Slim 애플리케이션을 빌드한 다음 drivers/drivers.php를 로드하고, 이어서 middlewares/middlewares.php, 마지막으로 모든 라우트 파일을 로드한 후 애플리케이션을 반환합니다.
스타터(composer create-project kipchak/starter my-api)로 생성된 프로젝트의 명령어:
composer test: 테스트를 실행합니다. 모든 변경 후 실행하십시오.composer openapi: OpenAPI 문서를openapi.yaml에 작성합니다. 문서에 문제가 있으면 실패합니다.docker compose up --watch: http://localhost:8080에서 API를 실행하고, 파일이 변경될 때 워커를 재시작합니다.
규칙
api/및tests/의 모든 PHP 파일은declare(strict_types=1);로 시작합니다. 확장할 목적이 아니라면 클래스는final로 만듭니다. 모든 프로퍼티, 매개변수, 반환 값에 타입을 지정합니다.- 컨트롤러는 얇게 유지합니다. 요청을 읽고, 모델을 호출하고, 응답을 반환합니다. 로직은
api/Models/에 속합니다. - DTO는 계약입니다. 모든 요청 및 응답 형태는
#[OA\Schema]와 각 프로퍼티에#[OA\Property](설명 및 예시)가 있는final readonlyDTO입니다. 컨트롤러는ref: '#/components/schemas/Name'을 사용하여 DTO 스키마를 참조하며 DTO의 필드를 인라인으로 정의하지 않습니다. 동일한 DTO가 요청 본문과 응답을 모두 설명합니다. - 응답은
Kipchak\Core\Components\Http\Response::json($response, $data, $status)를 통해 전달되며,$data를{"code": 200, "status": "OK", "data": ...}봉투로 감쌉니다. - 오류는 Slim의 HTTP 예외(
HttpNotFoundException,HttpBadRequestException,HttpUnauthorizedException,HttpForbiddenException,HttpMethodNotAllowedException)입니다. Error 미들웨어(kipchak/middleware-error)가 이를 동일한 봉투로 변환합니다. 예:{"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "No order has the ID 9."}. 다른 모든 예외는 클라이언트가 메시지를 볼 수 없는 500 오류가 됩니다. - 워커 모드. API는 한 번 부트되어 메모리에서 여러 요청을 처리합니다. 요청 데이터를 정적 프로퍼티, 전역 변수 또는 싱글톤에 절대 저장하지 마십시오. 정적 변수는 모든 요청에 동일한 것만 캐시할 수 있습니다.
- Kipchak 드라이버가 존재하는 서비스에는 클라이언트 라이브러리를 직접 사용하는 대신 Kipchak 드라이버를 사용하십시오(references/packages.md 참조). 관계형 데이터베이스는 Doctrine 드라이버를 사용합니다.
- 설정은
config/와 환경 변수에 있습니다. 설정 파일은Kipchak\Driver\Config\Config::get('kipchak.api')로 읽으며, 배열을 반환합니다. 설정 파일 내에서 환경 변수는Kipchak\Core\env('NAME', 'default')로 읽습니다. 컨트롤러나 모델에서getenv()를 호출하지 마십시오. - 로깅은 컨트롤러에서
$this->logger(Monolog, PSR-3)를 사용하고, 그 외에는Kipchak\Driver\Logger\Logger::get()를 사용합니다. - API 변경은 계약 변경입니다. DTO와 컨트롤러의 속성을 함께 업데이트한 다음 테스트를 업데이트하고, OpenAPI 문서가 여전히 경고 없이 생성되는지 확인하십시오.
엔드포인트 추가하기
다섯 단계를 따르십시오. 각 단계의 전체 코드는 references/endpoints.md에 있습니다. 엔드포인트를 작성하기 전에 먼저 읽으십시오.
- DTO를
api/DataTransferObjects/v1/에 작성합니다. - 모델을
api/Models/에 작성합니다: 로직, DTO를 반환합니다. 배열을 DTO로 매핑하려면 Valinor를 사용하십시오:(new MapperBuilder())->mapper()->map(Order::class, Source::array($row)). - 컨트롤러 메서드를
api/Controllers/v1/에 작성합니다.Kipchak\Core\Components\Controllers\Base를 확장하는 클래스에 시그니처(ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface와#[OA\Get],#[OA\Post](등) 속성(경로,operationId, 요약, 태그, 매개변수, 요청 본문, 응답)을 추가합니다. - 라우트를
routes/v1/<resource>.php에 작성합니다./v1그룹 내에:$group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']); - 테스트를
tests/에 작성합니다. 프로젝트의ApiTestCase를 확장하여 성공 및 오류 응답을 테스트합니다. 프로젝트의 OpenAPI 테스트가 예상 경로를 나열하는 경우 새 경로를 추가합니다.
참조
작업과 일치하는 참조를 읽으십시오:
- references/endpoints.md: 완전한 리소스(DTO, 모델, 컨트롤러, 라우트, 테스트), 요청 본문 및 검증, 쿼리 매개변수, 경로 매개변수.
- references/drivers.md: 드라이버 사용, 설정, Doctrine, 새 드라이버 작성.
- references/middleware.md: 전역, 그룹 및 라우트 미들웨어, 순서, 새 미들웨어 작성.
- references/worker-mode.md: 장기 실행 워커에서 안전한 것, 요청 본문, 연결, 응답 후 작업.
- references/packages.md: 모든 Kipchak 드라이버 및 미들웨어, 무료 및 엔터프라이즈.