Armeria — Netty 기반 마이크로서비스 프레임워크

import com.linecorp.armeria.server.Server;
import com.linecorp.armeria.server.ServerBuilder;

// Armeria 서버 기본 구성 — 놀라울 정도로 간결하다
Server server = Server.builder()
    .http(8080)
    // REST 서비스
    .annotatedService("/api", new MyRestService())
    // gRPC 서비스
    .service(GrpcService.builder()
        .addService(new MyGrpcServiceImpl())
        .build())
    // Thrift 서비스
    .service("/thrift", THttpService.of(new MyThriftHandler()))
    .build();

// 서버 시작
server.start().join();

클라이언트 요청
    │
    ▼
[ Armeria Server (Netty 기반) ]
    │
    ├── Content-Type: application/grpc  ──→  gRPC 서비스
    ├── Content-Type: application/x-thrift ──→  Thrift 서비스
    └── 경로 패턴 매칭 (/api/**)  ──→  REST 서비스

import com.linecorp.armeria.server.annotation.*;

public class MyRestService {

    // GET /api/users/{id}
    @Get("/users/{id}")
    public HttpResponse getUser(@Param("id") long id) {
        User user = userRepository.findById(id);
        return HttpResponse.ofJson(user);
    }

    // POST /api/users
    @Post("/users")
    public HttpResponse createUser(CreateUserRequest request) {
        // 비동기 처리도 자연스럽다
        return HttpResponse.from(
            userService.create(request)
                .thenApply(user -> HttpResponse.ofJson(HttpStatus.CREATED, user))
        );
    }
}

Armeria ServerBuilder
    │
    ▼
Netty ServerBootstrap 구성
    ├── bossGroup: NioEventLoopGroup (acceptor)
    ├── workerGroup: NioEventLoopGroup (I/O 처리)
    ├── channel: NioServerSocketChannel (또는 EpollServerSocketChannel)
    └── childHandler (ChannelPipeline):
        ├── SslHandler (TLS가 설정된 경우)
        ├── Http2FrameCodec (HTTP/2 프레이밍)
        ├── Http2MultiplexHandler (스트림 멀티플렉싱)
        └── Armeria 내부 핸들러 (라우팅, 서비스 디스패치)

Server server = Server.builder()
    .http(8080)
    // Netty ChannelOption 직접 설정
    .channelOption(ChannelOption.SO_BACKLOG, 1024)
    .childChannelOption(ChannelOption.SO_KEEPALIVE, true)
    .childChannelOption(ChannelOption.TCP_NODELAY, true)
    // worker EventLoop 스레드 수 지정
    .workerGroup(16)
    // 최대 연결 수 제한
    .maxNumConnections(10000)
    .annotatedService("/api", new MyRestService())
    .build();

[ Netty ChannelPipeline ]
바이트 → SslHandler → Http2FrameCodec → Http2MultiplexHandler → 비즈니스 핸들러

[ Armeria 데코레이터 체인 ]
HttpRequest → LoggingService → AuthService → MetricCollecting → 비즈니스 서비스

Server server = Server.builder()
    .http(8080)
    .annotatedService("/api", new MyRestService())
    // 데코레이터 체이닝 — 안쪽에서 바깥쪽 순서로 감싼다
    .decorator(LoggingService.newDecorator())        // 요청/응답 로깅
    .decorator(MetricCollectingService.newDecorator(  // 메트릭 수집
        MeterIdPrefixFunction.ofDefault("my.service")))
    .decorator(AuthService.newDecorator(              // 인증
        new MyAuthHandler()))
    .build();

요청 → Auth → Metric → Logging → 비즈니스 로직
응답 ← Auth ← Metric ← Logging ← 비즈니스 로직

// 요청 처리 시간을 측정하는 커스텀 데코레이터
public class TimingDecorator implements DecoratingHttpServiceFunction {

    @Override
    public HttpResponse serve(HttpService delegate, ServiceRequestContext ctx,
                              HttpRequest req) throws Exception {
        long start = System.nanoTime();

        // 원본 서비스에 위임
        HttpResponse response = delegate.serve(ctx, req);

        // 응답이 완료되면 시간 측정
        response.whenComplete().thenRun(() -> {
            long elapsed = System.nanoTime() - start;
            logger.info("{} {} took {}ms",
                req.method(), req.path(),
                TimeUnit.NANOSECONDS.toMillis(elapsed));
        });

        return response;
    }
}

// 사용
Server.builder()
    .annotatedService("/api", new MyRestService())
    .decorator(TimingDecorator::new)
    .build();

클라이언트 연결
    │
    ▼
[ TLS + ALPN 협상 (h2 선택) ]
    │
    ▼
[ Netty Http2FrameCodec ]  ← 바이너리 프레임 파싱
    │
    ▼
[ Netty Http2MultiplexHandler ]  ← 스트림별 자식 Channel 생성
    │
    ▼
[ Armeria HttpServerHandler ]  ← 서비스 라우팅 및 디스패치

Server server = Server.builder()
    .http(8080)          // h2c + HTTP/1.1 자동 감지
    .https(8443)         // h2 (TLS + ALPN)
    .tlsSelfSigned()     // 개발용 자체 서명 인증서
    .annotatedService("/api", new MyRestService())
    .build();

// 정적 엔드포인트 그룹
EndpointGroup staticGroup = EndpointGroup.of(
    Endpoint.of("server1.example.com", 8080),
    Endpoint.of("server2.example.com", 8080),
    Endpoint.of("server3.example.com", 8080)
);

// DNS 기반 서비스 디스커버리
EndpointGroup dnsGroup = DnsEndpointGroup.builder("my-service.internal")
    .port(8080)
    .ttl(10, 60) // 최소 10초, 최대 60초 TTL
    .build();

// ZooKeeper 기반 (별도 의존성)
EndpointGroup zkGroup = ZooKeeperEndpointGroup.builder(
        curatorFramework, "/services/my-service")
    .build();

// 가중 라운드로빈 (기본)
WebClient client = WebClient.builder("http", staticGroup)
    .endpointRemapper(endpoint ->
        endpoint.withWeight(endpoint.host().equals("server1") ? 3 : 1))
    .build();

// 엔드포인트 그룹으로 클라이언트 생성
WebClient client = WebClient.of(SessionProtocol.HTTP, staticGroup);

// 요청 — 자동으로 로드밸런싱된다
HttpResponse response = client.get("/api/users/1");

// 엔드포인트 헬스 체크 — 죽은 서버는 자동으로 제외
EndpointGroup healthChecked = HealthCheckedEndpointGroup.builder(
        staticGroup, "/internal/health")
    .protocol(SessionProtocol.HTTP)
    .retryInterval(Duration.ofSeconds(5))  // 5초마다 헬스 체크
    .build();

// 헬스 체크 통과한 서버에만 요청이 간다
WebClient client = WebClient.of(SessionProtocol.HTTP, healthChecked);

<!-- build.gradle 또는 pom.xml -->
<dependency>
    <groupId>com.linecorp.armeria</groupId>
    <artifactId>armeria-spring-boot3-starter</artifactId>
    <version>1.31.3</version>
</dependency>

@Configuration
public class ArmeriaConfig {

    @Bean
    public ArmeriaServerConfigurator armeriaServerConfigurator() {
        return builder -> {
            // gRPC 서비스 등록
            builder.service(GrpcService.builder()
                .addService(new MyGrpcServiceImpl())
                .build());

            // 데코레이터 추가
            builder.decorator(LoggingService.newDecorator());

            // DocService — Armeria의 내장 API 문서 & 디버그 도구
            builder.serviceUnder("/docs", DocService.builder().build());
        };
    }
}

[ Armeria Server (Netty 기반) ]
    │
    ├── /grpc/**  ──→  Armeria gRPC 서비스
    ├── /docs/**  ──→  Armeria DocService
    └── 나머지   ──→  내장 Tomcat (Spring MVC)

// 기존 Spring MVC 컨트롤러 — 그대로 동작한다
@RestController
@RequestMapping("/api/v1")
public class UserController {

    @GetMapping("/users/{id}")
    public User getUser(@PathVariable long id) {
        return userService.findById(id);
    }
}

// 새로운 gRPC 서비스 — 같은 서버에서 함께 동작한다
public class UserGrpcService extends UserServiceGrpc.UserServiceImplBase {

    @Override
    public void getUser(GetUserRequest request,
                        StreamObserver<GetUserResponse> observer) {
        // gRPC 구현
    }
}

builder.serviceUnder("/docs", DocService.builder()
    // 예제 요청 추가
    .exampleRequests(MyGrpcServiceGrpc.SERVICE_NAME,
        "GetUser",
        GetUserRequest.newBuilder().setId(1).build())
    .build());