POEM API 개요

Poem-openapi는 OpenAPI v3 사양을 준수하는 API를 손쉽게 구현할 수 있도록 지원하는 웹프레임워크이다. 이 프레임워크는 절차적 매크로를 활용하여 반복적인 코드를 자동으로 생성하므로, 개발자는 비즈니스 로직에 집중할 수 있도록 한다. 자동 생성된 Swagger UI 기반의 인터랙티브한 API 문서를 쉽게 확인가능하다.

소스

• Crate

[dependencies]
poem = "3"
poem-openapi = { version = "5", features = ["swagger-ui"]}
tokio = { version = "1", features = ["full"] }

• main.rs

use poem::{listener::TcpListener, Route};
use poem_openapi::{param::Query, payload::PlainText, OpenApi, OpenApiService};

struct Api;

#[OpenApi]
impl Api {
    #[oai(path = "/hello", method = "get")]
    async fn index(&self, name: Query<Option<String>>) -> PlainText<String> {
        match name.0 {
            Some(name) => PlainText(format!("hello, {}!", name)),
            None => PlainText("hello!".to_string()),
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    let api_service =
        OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000/api");
    let ui = api_service.swagger_ui();
    let app = Route::new().nest("/api", api_service).nest("/", ui);

    poem::Server::new(TcpListener::bind("0.0.0.0:3000"))
        .run(app)
        .await
}

소스 용도

REST API 백엔드 API SERVER 구축 기반

소스 설명

기능 확인

• CLI

curl http://localhost:3000/api/hello
hello!


curl http://localhost:3000/api/hello?name=backend
hello, backend!

• Swagger Web UI

http://localhost:3000

활용

Poem-openapi는 언제 유용할까?

✅ Rust 기반 웹 API를 개발할 때 → 안전하고 효율적인 API 구축 가능
✅ 자동화된 API 문서(Swagger)를 필요로 할 때 → OpenAPI 문서를 손쉽게 생성
✅ 타입 안정성을 중요하게 생각할 때 → 데이터 구조를 엄격하게 검증 가능
✅ 빠른 개발이 필요한 경우 → 어노테이션 기반 API 정의로 코드 작성이 간결

Poem-openapi를 사용할 때 유의해야 할 점

✅ 소규모 프로젝트나 빠른 API 개발에는 유용하지만, 대규모 고성능 서비스에는 Actix-web이나 Axum이 더 나을 수 있음.
✅ 생태계와 커뮤니티 지원이 적으므로 문제 해결 시 직접 해결해야 할 가능성이 높음.
✅ Rust 최신 버전에 의존할 가능성이 크므로 장기 프로젝트에서 업데이트 관리가 필요함.
✅ 자동 생성된 API 문서와 실제 API가 동기화되는지 주기적으로 확인해야 함(매크로 기반 코드 자동 생성 이슈).

성능 비교: Poem-openapi vs Spring Boot

📌 단순 요청 처리 성능 (RPS, 요청/초)

프레임워크	RPS (Requests per Second)	Latency (평균 응답 시간)
Poem-openapi	100K+ RPS	0.3~0.8ms
Spring Boot (Tomcat)	20K~30K RPS	5~10ms
Spring Boot (Netty)	40K~50K RPS	3~5ms

성능 차이가 나는 이유

✅ Poem-openapi (Rust)의 강점
Zero-cost abstraction (제로 비용 추상화) → 불필요한 런타임 오버헤드 없음
Hyper 기반 고성능 비동기 HTTP 서버 → Rust의 네이티브 비동기 모델 활용
GC(가비지 컬렉션) 없음 → Java처럼 정기적인 GC 동작이 없어 일관된 성능 유지
메모리 사용량이 낮음 → Java 대비 5~10배 낮은 메모리 사용

✅ Spring Boot (Java)의 단점
JVM & GC 오버헤드 → Java의 GC(Garbage Collection)가 성능 병목 발생
멀티스레드 기반 동시성 처리 → Rust의 async/await 모델보다 효율성이 낮음
Spring 자체가 무겁다 → 강력한 기능 제공하지만 오버헤드가 큼

실제 사용 사례 비교

📌 Poem-openapi를 추천하는 경우
✅ 초고성능 API 서버가 필요할 때
✅ 낮은 메모리 사용량이 중요한 경우
✅ Rust 생태계를 적극 활용하고 싶을 때

📌 Spring Boot를 추천하는 경우
✅ Java 기반의 대규모 엔터프라이즈 시스템 구축
✅ 기존 Spring 생태계를 활용해야 할 때
✅ 마이크로서비스 아키텍처에서 다양한 Spring 기능이 필요할 때

타 RUST OPENAPI 프레임워크 선택

"당장 최고의 성능이 필요하면 Actix-web + Paperclip, 하지만 유지보수성과 Rust 최신 스타일을 고려하면 Axum + Utoipa!"

💨 ✅ 성능(속도)이 가장 중요하다면?
👉 Actix-web + Paperclip

Actix-web은 Rust에서 가장 빠른 웹 프레임워크
초당 100K+ 요청 처리 가능
하지만 Paperclip은 비공식 라이브러리로 유지보수 불확실
🛠️ ✅ 유지보수 & 최신 Rust 스타일이 필요하다면?
👉 Axum + Utoipa

Axum은 미래 Rust 생태계와 잘 맞고 유지보수 가능성 높음
Utoipa는 현재 Rust에서 가장 인기 있는 OpenAPI 문서화 라이브러리
성능 차이가 크지 않으며 장기적으로는 Axum이 더 유리할 수도 있음

✅ Rust 초보자 / 빠른 개발 → Poem + Poem-openapi
→ 가장 쉬운 OpenAPI 지원, 문서화 자동 생성 (공식 지원)

✅ 최신 Rust 스타일 & 유지보수 용이성 → Axum + utoipa
→ 미래에도 유지보수 가능성이 높고, 새로운 Rust 생태계와 잘 맞음

✅ 고성능 / 엔터프라이즈급 API 서버 → Actix-web + Paperclip
→ Rust 웹 프레임워크 중 가장 빠르고, 대규모 트래픽 처리 가능

참고

ChatGPT

사이트

POEM-OPENAPI GitHub