Documentation
¶
Overview ¶
Package handler v1 API의 HTTP 요청 핸들러를 제공합니다.
이 패키지는 알림 전송 API의 핸들러 계층을 담당하며, HTTP 요청을 받아 검증하고, 비즈니스 로직을 호출한 후, 적절한 HTTP 응답을 반환합니다.
핸들러는 다음 책임을 가집니다:
- 요청 데이터 바인딩 및 유효성 검증
- Context에서 인증된 Application 정보 추출
- 비즈니스 로직(notification.Sender) 호출
- 성공/실패 응답 생성 및 반환
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidBody 요청 본문(Body)의 데이터 형식이 올바르지 않거나(예: 잘못된 JSON), 파싱에 실패했을 때 반환하는 에러입니다. ErrInvalidBody = httputil.NewBadRequestError("요청 본문을 파싱할 수 없습니다. JSON 형식을 확인해주세요") // ErrServiceStopped 서버 종료(Graceful Shutdown) 등으로 인해 서비스가 잠시 중지되었을 때 반환하는 에러입니다. ErrServiceStopped = httputil.NewServiceUnavailableError("서비스가 점검 중이거나 종료되었습니다. 관리자에게 문의해 주세요") // ErrServiceOverloaded 요청 대기열(Queue)이 가득 찼거나, 시스템 부하가 심해 요청을 처리할 수 없을 때 반환하는 에러입니다. ErrServiceOverloaded = httputil.NewServiceUnavailableError("일시적인 과부하로 알림을 처리할 수 없습니다. 잠시 후 다시 시도해주세요") // ErrServiceInterrupted 요청 처리 중 예기치 않은 시스템 오류나 인터럽트(Context Cancelled)가 발생했을 때 반환하는 에러입니다. ErrServiceInterrupted = httputil.NewInternalServerError("알림 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도해주세요") // ErrNotifierNotFound 해당 알림 채널(Notifier)을 찾을 수 없거나, 존재하지 않을 때 반환하는 에러입니다. ErrNotifierNotFound = httputil.NewNotFoundError("등록되지 않은 알림 채널입니다. 설정을 확인해 주세요") ErrNotifierUnavailable = httputil.NewServiceUnavailableError("해당 알림 채널이 사용 불가능한 상태입니다 (일시적 중단 또는 종료됨). 잠시 후 다시 시도해주세요") )
Functions ¶
func NewErrAppIDMismatch ¶
NewErrAppIDMismatch 요청 본문(Body)의 Application ID와 인증 정보(Header/Query)가 불일치할 때 반환하는 보안 에러를 생성합니다.
func NewErrValidationFailed ¶
NewErrValidationFailed 요청 데이터의 필수 값 누락, 형식 위반 등 유효성 검증(Validation)에 실패했을 때 반환하는 에러를 생성합니다.
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler v1 API 요청을 처리하는 핸들러입니다.
Handler는 HTTP 계층과 비즈니스 로직 계층 사이의 어댑터 역할을 수행하며, 의존성 주입을 통해 알림 전송 서비스를 주입받습니다.
주요 역할:
- HTTP 요청 바인딩 및 검증
- 비즈니스 로직 호출 (알림 전송)
- HTTP 응답 생성 (성공/실패)
참고: 인증은 미들웨어에서 처리되므로, 핸들러는 이미 검증된 Application 객체를 Context에서 추출하여 사용합니다.
func New ¶
func New(notificationSender contract.NotificationSender) *Handler
New Handler 인스턴스를 생성합니다.
Parameters:
- notificationSender: 알림 전송을 담당하는 Sender 구현체
Returns:
- 초기화된 Handler 포인터
func (*Handler) PublishNotificationHandler ¶
PublishNotificationHandler godoc @Summary 알림 메시지 발송 @Description 외부 애플리케이션에서 텔레그램 등의 메신저로 알림 메시지를 전송합니다. @Description @Description 이 API를 사용하려면 사전에 등록된 애플리케이션 ID와 App Key가 필요합니다. @Description 설정 파일(notify-server.json)의 notify_api.applications에 애플리케이션을 등록해야 합니다. @Description @Description ## 인증 방식 @Description - **권장**: X-App-Key 및 X-Application-Id 헤더로 전달 @Description - **레거시**: app_key 쿼리 파라미터 및 본문의 application_id로 전달 (하위 호환성 유지) @Description @Description ## 사용 예시 (로컬 환경) @Description ### 헤더 방식 (권장) @Description ```bash @Description curl -X POST "http://localhost:2443/api/v1/notifications" \ @Description -H "Content-Type: application/json" \ @Description -H "X-App-Key: your-app-key" \ @Description -H "X-Application-Id: my-app" \ @Description -d '{"application_id":"my-app","message":"테스트 메시지","error_occurred":false}' @Description ``` @Description @Description ### 쿼리 파라미터 방식 (레거시) @Description ```bash @Description curl -X POST "http://localhost:2443/api/v1/notifications?app_key=your-app-key" \ @Description -H "Content-Type: application/json" \ @Description -d '{"application_id":"my-app","message":"테스트 메시지","error_occurred":false}' @Description ``` @Description @Description ## 응답 예시 @Description ### 성공 (200 OK) @Description ```json @Description {"result_code":0,"message":"성공"} @Description ``` @Description @Description ### 실패 (400 Bad Request) @Description ```json @Description {"result_code":400,"message":"애플리케이션 ID는 필수 항목입니다"} @Description ``` @Tags Notification @Accept json @Produce json @Param X-App-Key header string false "Application Key (인증용, 권장)" example(your-app-key-here) @Param X-Application-Id header string false "Application ID (성능 최적화용, 권장)" example(my-app) @Param app_key query string false "Application Key (인증용, 레거시)" example(your-app-key-here) @Param message body request.NotificationRequest true "알림 메시지 정보" @Success 200 {object} response.SuccessResponse "성공" @Failure 400 {object} response.ErrorResponse "잘못된 요청 - 필수 필드 누락, JSON 형식 오류, 메시지 길이 초과(최대 4096자)" @Failure 401 {object} response.ErrorResponse "인증 실패 - App Key 누락, 잘못된 App Key, 미등록 애플리케이션" @Failure 500 {object} response.ErrorResponse "서버 내부 오류" @Failure 503 {object} response.ErrorResponse "서비스 일시 불가 - 알림 큐 포화 또는 시스템 종료 중" @Security ApiKeyAuth @Router /api/v1/notifications [post]
Source Files