HeuJung
ea58c606a2
공개 제보 — 파일 스토리지에서 S3 를 선택해 저장해도 실제 파일 저장이 동작하지 않던 결함의 전면 수정. - S3 어댑터(league/flysystem-aws-s3-v3)·predis 를 코어 기본 의존성으로 포함 — 어댑터 부재 즉사, phpredis 확장 없는 서버의 redis 선택 전면 다운 차단 (부트 시 확장 부재 감지 → predis 자동 폴백) - storage_driver=s3 저장 시 코어 첨부 업로드 디스크를 s3 로 전환 (ATTACHMENT_DISK env 명시가 항상 우선, 기존 행은 저장 당시 disk 로 서빙) - 첨부·템플릿 레이아웃 첨부 서빙을 행 disk 를 따르는 스토리지 스트림으로 교체 — 로컬 절대 경로 전제 fileResponse 는 S3 행에서 filemtime stat 500 (streamedFileResponse: 행 메타 기반 ETag/304/Cache-Control) - S3 호환 스토리지(R2/MinIO/NCP) 연결 지원: 엔드포인트 URL·path-style 설정 신설, 리전 목록 선택 → 자유 입력 전환, 연결 테스트를 실제 저장 경로와 동일 설정(endpoint/path-style)으로 정렬 - 사용 불능 드라이버(어댑터·PHP 확장 부재)의 저장/테스트 요청을 사유와 함께 422 로 차단하는 서버 게이트 신설 (DriverRegistryService 능력 판정) - 웹소켓 연결 테스트에 서버(백엔드 발송용) endpoint 검사 추가 — 클라이언트만 검사해 테스트 성공 + 실제 발송 실패가 가능하던 비대칭 해소 - env 빈 값(`KEY=`) 함정 정규화: AWS_URL/AWS_ENDPOINT/ATTACHMENT_DISK 빈 문자열을 미설정으로 취급 (config 정규화 + 예시 파일 주석 처리) - 플러그인 드라이버 폴백의 log 카테고리 죽은 키(logging.default) 정정 및 websocket 유령 설정 키 제거 - 실 AWS S3 종단 검증 완료 (설정 저장 → 업로드 S3 실저장 → 서빙 200/304)
301 lines
10 KiB
PHP
301 lines
10 KiB
PHP
<?php
|
|
|
|
namespace App\Http\Controllers\Api\Base;
|
|
|
|
use App\Helpers\ResponseHelper;
|
|
use App\Http\Controllers\Controller;
|
|
use App\Models\User;
|
|
use Illuminate\Http\JsonResponse;
|
|
use Illuminate\Http\Response;
|
|
use Illuminate\Support\Facades\Auth;
|
|
use Symfony\Component\HttpFoundation\BinaryFileResponse;
|
|
use Symfony\Component\HttpFoundation\StreamedResponse;
|
|
|
|
/**
|
|
* API 컨트롤러의 최상위 베이스 클래스
|
|
*
|
|
* 모든 API 컨트롤러가 공통으로 사용하는 기능을 제공합니다.
|
|
* Admin, Auth, Public 컨트롤러는 이 클래스를 상속받습니다.
|
|
*/
|
|
abstract class BaseApiController extends Controller
|
|
{
|
|
/**
|
|
* 성공 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param mixed $data 응답 데이터
|
|
* @param int $statusCode HTTP 상태 코드
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function success(
|
|
string $messageKey = 'common.success',
|
|
mixed $data = null,
|
|
int $statusCode = 200,
|
|
array $messageParams = []
|
|
) {
|
|
return ResponseHelper::success($messageKey, $data, $statusCode, $messageParams, 'core');
|
|
}
|
|
|
|
/**
|
|
* 실패 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param int $statusCode HTTP 상태 코드
|
|
* @param mixed $errors 오류 정보
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function error(
|
|
string $messageKey = 'common.failed',
|
|
int $statusCode = 400,
|
|
mixed $errors = null,
|
|
array $messageParams = []
|
|
) {
|
|
return ResponseHelper::error($messageKey, $statusCode, $errors, $messageParams, 'core');
|
|
}
|
|
|
|
/**
|
|
* 리소스와 함께 성공 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param mixed $resource JSON 리소스
|
|
* @param int $statusCode HTTP 상태 코드
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function successWithResource(
|
|
string $messageKey = 'common.success',
|
|
mixed $resource = null,
|
|
int $statusCode = 200,
|
|
array $messageParams = []
|
|
) {
|
|
return ResponseHelper::successWithResource($messageKey, $resource, $statusCode, $messageParams, 'core');
|
|
}
|
|
|
|
/**
|
|
* 현재 인증된 사용자를 반환합니다.
|
|
*
|
|
* @return User|null
|
|
*/
|
|
protected function getCurrentUser()
|
|
{
|
|
return Auth::user();
|
|
}
|
|
|
|
/**
|
|
* Not Found 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function notFound(
|
|
string $messageKey = 'common.not_found',
|
|
array $messageParams = []
|
|
) {
|
|
return $this->error($messageKey, 404, null, $messageParams);
|
|
}
|
|
|
|
/**
|
|
* Unauthorized 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function unauthorized(
|
|
string $messageKey = 'common.unauthorized',
|
|
array $messageParams = []
|
|
) {
|
|
return $this->error($messageKey, 401, null, $messageParams);
|
|
}
|
|
|
|
/**
|
|
* Forbidden 응답을 생성합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function forbidden(
|
|
string $messageKey = 'common.forbidden',
|
|
array $messageParams = []
|
|
) {
|
|
return $this->error($messageKey, 403, null, $messageParams);
|
|
}
|
|
|
|
/**
|
|
* Validation Error 응답을 생성합니다.
|
|
*
|
|
* @param mixed $errors 검증 오류
|
|
* @param string $messageKey 메시지 키
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse
|
|
*/
|
|
protected function validationError(
|
|
mixed $errors,
|
|
string $messageKey = 'common.validation_failed',
|
|
array $messageParams = []
|
|
) {
|
|
return $this->error($messageKey, 422, $errors, $messageParams);
|
|
}
|
|
|
|
/**
|
|
* 파일 응답을 반환합니다 (ETag 및 캐싱 헤더 포함).
|
|
*
|
|
* @param string $filePath 파일 경로
|
|
* @param string $mimeType MIME 타입
|
|
* @param int $maxAge 캐시 유지 시간 (초, 기본: 1년)
|
|
*/
|
|
protected function fileResponse(string $filePath, string $mimeType, int $maxAge = 31536000): BinaryFileResponse|Response
|
|
{
|
|
// ETag 생성 (파일 수정 시간 + 파일 크기 기반)
|
|
$etag = md5(filemtime($filePath).filesize($filePath));
|
|
|
|
// If-None-Match 헤더 확인 (ETag 비교)
|
|
if (request()->header('If-None-Match') === $etag) {
|
|
return response('', 304)->header('ETag', $etag); // 304 Not Modified
|
|
}
|
|
|
|
// 환경별 캐싱 정책
|
|
$cacheControl = app()->environment('production')
|
|
? "public, max-age={$maxAge}, immutable" // 프로덕션: immutable 추가
|
|
: 'no-cache'; // 개발: 캐싱 비활성화
|
|
|
|
$response = response()->file($filePath, [
|
|
'Content-Type' => $mimeType,
|
|
'Expires' => gmdate('D, d M Y H:i:s', time() + $maxAge).' GMT',
|
|
'ETag' => $etag,
|
|
]);
|
|
|
|
// Cache-Control 헤더를 수동으로 설정 (기본 헤더 덮어쓰기)
|
|
$response->headers->set('Cache-Control', $cacheControl);
|
|
|
|
return $response;
|
|
}
|
|
|
|
/**
|
|
* 스토리지 스트림 응답에 ETag/캐싱 헤더를 부착합니다 (fileResponse 의 디스크 인지 대응).
|
|
*
|
|
* fileResponse() 는 로컬 절대 경로 전제(filemtime/filesize)라 S3 등 원격 디스크
|
|
* 행에는 쓸 수 없습니다. 원격/로컬 공통 서빙은 StorageInterface::response() 가
|
|
* 만든 스트림에 본 메서드로 동일한 캐싱 계약(ETag/304/Cache-Control/Expires)을
|
|
* 입힙니다. ETag 는 파일 stat 대신 호출자가 준 결정적 소스(행 메타)로 만듭니다.
|
|
*
|
|
* @param StreamedResponse $response 스토리지 인라인 스트림 응답
|
|
* @param string $etagSource ETag 소스 문자열 (디스크·경로·수정시각·크기 등 행 메타)
|
|
* @param int $maxAge 캐시 유지 시간 (초)
|
|
* @return StreamedResponse|Response 스트림 응답 또는 304
|
|
*/
|
|
protected function streamedFileResponse(StreamedResponse $response, string $etagSource, int $maxAge): StreamedResponse|Response
|
|
{
|
|
$etag = md5($etagSource);
|
|
|
|
// If-None-Match 헤더 확인 (ETag 비교)
|
|
if (request()->header('If-None-Match') === $etag) {
|
|
return response('', 304)->header('ETag', $etag);
|
|
}
|
|
|
|
// 환경별 캐싱 정책 (fileResponse 와 동일)
|
|
$cacheControl = app()->environment('production')
|
|
? "public, max-age={$maxAge}, immutable"
|
|
: 'no-cache';
|
|
|
|
$response->headers->set('ETag', $etag);
|
|
$response->headers->set('Expires', gmdate('D, d M Y H:i:s', time() + $maxAge).' GMT');
|
|
$response->headers->set('Cache-Control', $cacheControl);
|
|
|
|
return $response;
|
|
}
|
|
|
|
/**
|
|
* JSON 응답을 반환합니다 (캐싱 헤더 포함).
|
|
*
|
|
* @param mixed $data JSON으로 변환할 데이터
|
|
* @param int $maxAge 캐시 유지 시간 (초, 기본: 1시간)
|
|
* @param int $status HTTP 상태 코드
|
|
* @return JsonResponse JSON 응답
|
|
*/
|
|
protected function cachedJsonResponse(mixed $data, int $maxAge = 3600, int $status = 200): JsonResponse
|
|
{
|
|
return response()->json($data, $status, [
|
|
'Cache-Control' => "public, max-age={$maxAge}",
|
|
], ResponseHelper::JSON_ENCODE_OPTIONS);
|
|
}
|
|
|
|
/**
|
|
* ETag를 생성합니다.
|
|
*
|
|
* @param mixed $data 해시할 데이터
|
|
* @return string ETag 값 (따옴표 포함)
|
|
*/
|
|
protected function generateETag(mixed $data): string
|
|
{
|
|
$content = is_string($data) ? $data : json_encode($data);
|
|
|
|
return '"'.md5($content).'"';
|
|
}
|
|
|
|
/**
|
|
* 클라이언트 캐시가 유효한지 확인합니다.
|
|
*
|
|
* @param string $etag 현재 ETag 값
|
|
* @return bool 캐시가 유효하면 true
|
|
*/
|
|
protected function isNotModified(string $etag): bool
|
|
{
|
|
$clientEtag = request()->header('If-None-Match');
|
|
|
|
return $clientEtag !== null && $clientEtag === $etag;
|
|
}
|
|
|
|
/**
|
|
* 304 Not Modified 응답을 반환합니다.
|
|
*
|
|
* @param string $etag ETag 값
|
|
* @param int $maxAge 캐시 TTL (초)
|
|
* @return Response 304 응답
|
|
*/
|
|
protected function notModifiedResponse(string $etag, int $maxAge = 3600): Response
|
|
{
|
|
return response('', 304)
|
|
->header('ETag', $etag)
|
|
->header('Cache-Control', "public, max-age={$maxAge}");
|
|
}
|
|
|
|
/**
|
|
* 캐시 헤더와 함께 성공 응답을 반환합니다.
|
|
*
|
|
* 클라이언트의 ETag가 일치하면 304 Not Modified를 반환합니다.
|
|
*
|
|
* @param string $messageKey 메시지 키
|
|
* @param mixed $data 응답 데이터
|
|
* @param int $maxAge 캐시 TTL (초, 기본: 1시간)
|
|
* @param array $messageParams 메시지 매개변수
|
|
* @return JsonResponse|Response JSON 응답 또는 304 응답
|
|
*/
|
|
protected function successWithCache(
|
|
string $messageKey = 'common.success',
|
|
mixed $data = null,
|
|
int $maxAge = 3600,
|
|
array $messageParams = []
|
|
): JsonResponse|Response {
|
|
$etag = $this->generateETag($data);
|
|
|
|
// 304 Not Modified 처리
|
|
if ($this->isNotModified($etag)) {
|
|
return $this->notModifiedResponse($etag, $maxAge);
|
|
}
|
|
|
|
return response()->json([
|
|
'success' => true,
|
|
'message' => __($messageKey, $messageParams),
|
|
'data' => $data,
|
|
], 200, [], ResponseHelper::JSON_ENCODE_OPTIONS)
|
|
->header('ETag', $etag)
|
|
->header('Cache-Control', "public, max-age={$maxAge}")
|
|
->header('Vary', 'Accept-Encoding, Accept-Language');
|
|
}
|
|
}
|