axum server github: 저장소에서 서버 띄우기까지

axum server github를 찾는 분들이 가장 먼저 헷갈리는 지점은 "저장소에서 무엇을 가져오고, 문서에서 무엇을 확인하는가"입니다. axum은 Tokio 팀이 관리하는 Rust 웹 프레임워크이고, GitHub 저장소는 소스 코드와 예제, 이슈 트래커의 역할을 하며 API 레퍼런스는 별도 문서 사이트가 담당합니다. 이 글은 저장소를 처음 열어 본 백엔드 개발자가 예제 서버를 로컬에서 실행하고, 이후 실제 배포 구조로 옮겨 갈 때 확인해야 할 순서를 정리합니다.

한눈에 보기

axum 저장소를 이해할 때 기억하면 좋은 구분은 세 가지입니다. 첫째, 저장소는 워크스페이스 형태로 여러 크레이트와 예제를 함께 담고 있습니다. 둘째, 문서 사이트는 릴리스된 버전을 기준으로 API 시그니처와 타입 설명을 제공합니다. 셋째, 예제 디렉터리는 저장소 안에서만 완결되는 실행 가능한 샘플 모음이라 그대로 복사해도 되고, 참고만 하고 자기 프로젝트에 맞게 다시 쓰셔도 됩니다.

서버를 띄우는 최소 경로는 단순합니다. Rust 툴체인을 준비하고, 저장소를 클론한 뒤, 예제 중 하나를 지정해 실행하면 됩니다. 문제는 그다음 단계입니다. 예제는 학습용으로 얇게 작성되어 있어서, 실제 서비스에 필요한 상태 공유나 미들웨어, 로깅, 종료 처리 같은 요소는 별도로 조립해야 합니다. 이 글에서는 그 경계를 명확히 나눠 설명합니다.

저장소와 문서의 역할 비교

같은 axum이라도 어디를 보느냐에 따라 얻는 정보가 다릅니다. 아래 표는 상황별로 어디를 우선 확인하면 좋은지 정리한 것입니다.

표에서 보시는 것처럼 저장소와 문서는 대체 관계가 아니라 보완 관계입니다. 컴파일 오류가 나면 문서에서 시그니처를 확인하고, 왜 그런 설계인지 궁금하면 저장소의 소스와 이슈를 보는 순서가 효율적입니다.

단계별로 예제 서버 실행하기

Rust 툴체인 준비

먼저 rustup으로 툴체인을 설치하고 cargo 명령이 동작하는지 확인합니다. axum은 비동기 런타임 위에서 동작하므로 Tokio에 대한 이해가 함께 필요합니다. 툴체인 버전은 저장소의 안내를 따르시는 편이 안전합니다.

저장소 클론과 예제 위치 확인

저장소를 클론한 뒤 예제 디렉터리 목록을 훑어보세요. 라우팅, 상태 공유, 미들웨어, 웹소켓, 정적 파일 제공처럼 주제별로 나뉘어 있어서 필요한 샘플을 빠르게 찾을 수 있습니다. 목록만 봐도 axum이 어떤 기능을 1급으로 다루는지 감이 잡힙니다.

의존성 추가 방식 두 가지

예제를 그대로 실행할 때와 내 프로젝트에 axum을 추가할 때는 절차가 다릅니다. 새 프로젝트라면 아래처럼 의존성을 추가하는 방법이 가장 간단합니다.

cargo new axum-server-demo
cd axum-server-demo
cargo add axum
cargo add tokio --features tokio/full

버전은 직접 적지 않고 cargo add가 해석하도록 두면, 이후 업그레이드 시점에 Cargo.lock을 기준으로 재현성을 유지하기 좋습니다. 저장소 예제를 실행할 때는 클론한 디렉터리에서 예제 이름을 지정해 실행합니다.

cargo run -p example-hello-world

예제 이름은 저장소의 예제 목록에서 확인한 값을 그대로 사용하셔야 합니다.

최소 서버 코드

문서와 예제에서 공통적으로 확인할 수 있는 최소 구성은 다음과 같습니다. 라우터를 만들고, 리스너를 바인딩한 뒤, serve 함수에 넘기는 흐름입니다.

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(|| async { "hello" }));

let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") .await .unwrap();

axum::serve(listener, app).await.unwrap();

}

핵심은 Router가 요청을 처리하는 값이고, serve가 그 라우터를 실제 소켓에 연결한다는 점입니다. 이 분리가 명확하기 때문에 테스트에서 라우터만 떼어내 검증하기도 쉽습니다.

응답 확인

서버를 실행한 뒤에는 같은 주소로 요청을 보내 응답 본문이 돌아오는지 확인합니다. 여기까지 되면 저장소에서 서버를 띄우는 기본 경로는 끝난 것입니다. 다음 단계는 이 최소 구성을 실제 서비스 형태로 확장하는 작업입니다.

상황별 선택 가이드

학습과 데모 목적

저장소 예제를 그대로 실행하는 방식이 가장 빠릅니다. 예제는 특정 주제 하나에 집중되어 있어서 코드를 읽는 것만으로도 패턴이 눈에 들어옵니다. 다만 예제끼리 전제가 다르므로, 여러 예제를 섞어 붙일 때는 의존성과 모듈 구조를 다시 정리해야 합니다.

실제 서비스로 확장

이 경우에는 예제를 복사하기보다 내 프로젝트에 의존성을 추가하고 모듈을 나누는 편이 좋습니다. 라우터 정의, 핸들러, 상태 구조체, 설정 로딩을 분리하고, Tower 생태계의 미들웨어를 조합해 로깅과 타임아웃을 붙이는 흐름이 일반적입니다. axum이 Tower 서비스 추상화 위에 서 있다는 점을 이해하면 미들웨어 선택지가 넓어집니다.

기존 서비스에 일부만 도입

기존에 다른 프레임워크를 쓰고 있다면, 라우팅 계층만 axum으로 옮기는 방식도 검토할 수 있습니다. 이때는 상태 공유 방식과 에러 변환 규칙을 먼저 정해야 합니다. 핸들러가 반환하는 에러 타입을 하나로 통일해 두면 이후 확장이 편해집니다.

주의할 점

첫째, 저장소의 기본 브랜치 코드와 문서 사이트 내용이 항상 일치하지는 않습니다. 문서는 릴리스 기준이고 저장소는 다음 변경이 섞여 있을 수 있으니, 컴파일이 안 될 때는 어느 쪽을 보고 있는지 먼저 확인하세요.

둘째, 저장소는 워크스페이스이므로 실행 위치가 중요합니다. 루트에서 아무 예제나 실행하면 패키지 지정이 필요하다는 오류를 만나게 됩니다. 예제 이름을 정확히 지정하거나 해당 디렉터리로 이동해 실행하세요.

셋째, 의존성 버전은 고정하고 잠금 파일을 저장소에 커밋해 두는 편이 안전합니다. 배포 환경과 개발 환경의 해석 결과가 달라지면 원인 파악이 어려워집니다.

넷째, 비동기 런타임 설정을 임의로 바꾸지 마세요. 런타임 종류와 워커 설정은 처리량과 지연에 직접 영향을 주므로, 변경할 때는 근거를 남기고 별도로 검증하는 절차가 필요합니다.

자주 묻는 질문

axum 저장소를 클론하지 않고 예제 코드만 복사해 써도 되나요?

가능합니다. 예제는 독립적으로 읽히도록 작성되어 있어서 필요한 부분만 가져다 자기 프로젝트에 맞게 고치면 됩니다. 다만 예제가 전제하는 의존성과 모듈 구조를 함께 옮기지 않으면 컴파일 오류가 날 수 있으니, 사용한 항목을 하나씩 확인하며 가져오시길 권합니다.

GitHub의 기본 브랜치 코드와 문서 사이트 설명이 다르게 보이는 이유는 무엇인가요?

문서 사이트는 릴리스된 버전을 기준으로 만들어지고, 저장소의 기본 브랜치에는 아직 릴리스되지 않은 변경이 포함될 수 있기 때문입니다. 그래서 함수 시그니처가 어긋나 보일 때는 내가 사용하는 버전이 무엇인지부터 확인하는 것이 순서입니다. 필요하면 저장소의 릴리스 태그를 기준으로 코드를 읽으세요.

axum 서버를 배포할 때 저장소에서 무엇을 먼저 확인해야 하나요?

예제 목록에서 내 구성과 가장 가까운 샘플을 찾고, 그 샘플이 어떤 런타임 설정과 미들웨어를 전제하는지 확인하는 것이 좋습니다. 이어서 릴리스 노트에서 동작 변경이 있었는지 살펴보면 배포 후 예상치 못한 차이를 줄일 수 있습니다. 저장소는 원인 추적용, 문서는 사용법 확인용으로 나눠 쓰는 습관이 도움이 됩니다.

예제를 실행했는데 패키지를 찾을 수 없다는 오류가 납니다.

워크스페이스 루트에서 예제 이름을 지정하지 않고 실행했을 가능성이 큽니다. 예제 이름을 정확히 지정하거나 해당 예제 디렉터리로 이동해 실행해 보세요. 저장소의 예제 목록에 적힌 이름과 실제 패키지 이름이 같은지도 함께 확인하시면 좋습니다.

출처

• axum 공식 GitHub 저장소: https://github.com/tokio-rs/axum
• axum API 문서(docs.rs): https://docs.rs/axum/latest/axum/
• axum 공식 예제 모음: https://github.com/tokio-rs/axum/tree/main/examples

운영 관점에서 함께 읽으면 좋은 글로는 Tokio 공식 문서의 비동기 런타임 안내를 권합니다. axum 서버를 실제로 운영하다 보면 런타임 설정과 종료 처리, 미들웨어 조합에서 판단할 일이 많아지는데, 공식 문서의 런타임 설명을 먼저 읽어 두면 저장소 예제를 응용할 때 시행착오가 줄어듭니다. 관련 자료는 https://tokio.rs 에서 확인하실 수 있습니다.