🦀

260524_1718_axum hello_world

Axum Hello World

cargo build

•

async@awaits-MacBook-Air 260412_1712_axum_helloworld % cargo build

cargo run

•

async@awaits-MacBook-Air 260412_1712_axum_helloworld % cargo run

Explain

A minimal HTTP web server built with Axum 0.8 and Tokio. The server exposes a single route that responds with plain text: Hello, World!.

Overview

This project demonstrates the smallest useful Axum application:

•

One GET / route

•

Plain-text response body

•

Async request handling on the Tokio runtime

•

No shared application state, middleware, or database

Axum sits on top of Hyper and Tower. You define routes with a Router, attach handlers, bind a TCP listener, and serve requests with axum::serve.

Requirements

Tool	Version used	Notes
Rust	1.84+	Edition 2021
Cargo	1.84+	Bundled with Rust
OS	Any	macOS, Linux, and Windows

No external services (database, Redis, etc.) are required.

Project Structure

260412_1712_axum_helloworld/
├── Cargo.toml          # Crate metadata and dependencies
├── README.md           # This document
└── src/
    └── main.rs         # Application entry point and route handlers
Plain Text
복사

Dependencies

Defined in Cargo.toml:

Crate	Version	Role
axum	0.8	Web framework: routing, handlers, HTTP serving
tokio	1.x	Async runtime (full features: I/O, macros, multi-thread scheduler)

Axum pulls in Hyper, Tower, and HTTP types transitively. You do not need to add them explicitly for this example.

How It Works

1. Route definition

let app = Router::new().route("/", get(hello_world));
Rust
복사

•

Router::new() creates an empty router.

•

.route("/", get(...)) registers GET / and maps it to the hello_world handler.

•

Handlers are async functions. Axum runs them on the Tokio runtime.

2. Handler

async fn hello_world() -> &'static str {
    "Hello, World!"
}
Rust
복사

Returning &'static str tells Axum to send a 200 OK response with Content-Type: text/plain; charset=utf-8 and the string as the body. No manual response building is required for this simple case.

3. TCP listener

let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
Rust
복사

The server listens on port 3000 on all network interfaces (0.0.0.0). Use 127.0.0.1:3000 if you only want local access.

4. HTTP server

axum::serve(listener, app).await?;
Rust
복사

axum::serve accepts connections on the listener and dispatches HTTP requests to the router. It supports HTTP/1.1 and HTTP/2 (when enabled via features).

Request flow

Client (browser/curl)
    │
    ▼
TcpListener (port 3000)
    │
    ▼
axum::serve
    │
    ▼
Router  ──►  GET /  ──►  hello_world()  ──►  "Hello, World!"
Plain Text
복사

Build and Run

From the project root:

cd /Users/async/glory/Schedule/code/200518_0157_rs/axum/260412_1712_axum_helloworld
cargo run
Bash
복사

First run downloads and compiles dependencies; later runs are faster.

Expected console output:

Server listening on <http://localhost:3000>
Plain Text
복사

Press Ctrl+C to stop the server.

Release build (optional)

For optimized binaries:

cargo run --release
Bash
복사

Verify the Server

With the server running, in another terminal:

curl <http://localhost:3000>
Bash
복사

Expected response:

Hello, World!
Plain Text
복사

You can also open http://localhost:3000 in a browser; the same text should appear.

HTTP details

Item	Value
Method	GET
Path	/
Status	200 OK
Body	Hello, World!
Content-Type	text/plain; charset=utf-8 (inferred by Axum)

Other paths (e.g. /foo) return 404 Not Found because no route is registered for them.

Configuration

Setting	Location	Default value
Listen address	src/main.rs	0.0.0.0:3000
Axum version	Cargo.toml	0.8
Tokio features	Cargo.toml	full

To change the port, edit the LISTEN_ADDR constant in src/main.rs and update the println! message if desired.

Common Commands

Command	Description
cargo run	Build and run in debug mode
cargo build	Compile without running
cargo build --release	Optimized build
cargo check	Type-check without full link
cargo clean	Remove target/ build artifacts

Troubleshooting

Address already in use

If port 3000 is taken:

Error: failed to bind TCP listener
Plain Text
복사

Fix: Stop the other process using port 3000, or change LISTEN_ADDR to another port (e.g. 0.0.0.0:8080).

On macOS/Linux, find the process:

lsof -i :3000
Bash
복사

Cannot connect from another machine

Binding to 127.0.0.1 only accepts local connections. This project uses 0.0.0.0, which accepts remote connections if your firewall allows it.

Compile errors after upgrading Axum

Axum 0.8 changed path parameter syntax from :name to {name}. This project has no path parameters, so upgrades are straightforward. See the Axum 0.8 announcement for breaking changes when extending the app.

Next Steps

Ideas for extending this server:

More routes — Add GET /health for health checks.

JSON responses — Return Json(...) with serde for structured APIs.

Path parameters — Use /hello/{name} (Axum 0.8 syntax).

Middleware — Logging, CORS, or compression via Tower layers.

Shared state — Router::with_state for database pools or config.

Tests — axum::Router can be tested with tower::ServiceExt without binding a real port.

References

•

Axum documentation

•

Axum GitHub repository

•

Tokio tutorial

•

The Rust Async Book

License

This example is provided as-is for learning purposes. Add a license file if you plan to distribute or publish the crate.

axum/260412_1712_axum_helloworld/src/main.rs

use axum::{routing::get, Router};
/*
use 키워드: 외부 creates (axum)에 정의된 기능을 현재 소스코드 스코프로 가져와 긴 경로 생략 가능하게 함
중괄호 { ... } (Use Group): 동일한 루트 경로(axum)에서 여러 아이템(routing::get, Router)을 한 줄로 묶어 효율적으로 수입(Import)하는 문법
Router: Axum 프레임워크의 핵심 타입으로, 특정 HTTP 경로(URL)와 이를 처리할 핸들러 함수를 매핑해주는 웹 서버의 이정표 역할
routing::get: HTTP 메서드 중 조회 목적의 GET 요청만을 필터링하여 특정 핸들러에 연결해주는 라우팅 매칭 헬퍼 함수
*/

const LISTEN_ADDR: &str = "0.0.0.0:3001";
/*
const 키워드: 컴파일 시점에 값이 결정되는 불변의 '상수'를 정의 (프로그램 실행 중 절대 변경 불가)
LISTEN_ADDR: 상수의 이름으로, 관례에 따라 전체 대문자와 언더바(_) 스네이크 케이스로 명명
: &str: 상수의 타입을 명시한 것으로, 메모리에 고정된 문자열 데이터의 주소와 길이를 가리키는 고정 크기 문자열 슬라이스 타입 (Rust에서 const 정의 시 타입 명시는 필수)
= "0.0.0.0:3001";: 웹 서버가 요청을 기다릴(Listen) 주소와 포트를 지정
0.0.0.0: 특정 IP가 아닌, 서버 컴퓨터에 할당된 모든 네트워크 인터페이스(랜카드)로부터의 접속을 전부 허용하겠다는 의미
3001: 외부 클라이언트가 이 웹 서버에 접속하기 위해 통과해야 하는 문 번호(포트 번호)
*/

async fn hello_world() -> &'static str {
    "Hello, World!"
}
/*
hello_world: 루트 경로 `/`에 대한 HTTP 요청을 처리하는 핸들러(요청 처리 함수)
async fn: 비동기 함수를 선언하는 키워드 — 함수 내부에서 I/O 대기 등이 발생해도 스레드를 블로킹하지 않고 다른 작업에 양보할 수 있음
호출 측에서는 이 함수의 결과를 사용할 때 반드시 `.await`로 완료를 기다려야 함
Axum은 Tokio 비동기 런타임 위에서 동작하므로, 핸들러를 async fn으로 작성하는 것이 일반적
-> &'static str: 함수의 반환 타입 — 프로그램 전체 수명(static) 동안 유효한 문자열 슬라이스의 참조
Axum은 이 반환값을 HTTP 200 OK 응답으로 자동 변환하며, Content-Type은 text/plain으로 설정됨
단순 텍스트 응답의 경우 IntoResponse 트레이트 덕분에 Response 타입을 직접 만들 필요 없음
"Hello, World!": 함수 본문의 마지막 표현식 — 세미콜론(;)이 없으므로 이 값이 함수의 반환값이 됨
*/

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

    let listener = tokio::net::TcpListener::bind(LISTEN_ADDR)
        .await
        .expect("failed to bind TCP listener");

    println!("Server listening on http://localhost:3001");

    axum::serve(listener, app).await.expect("server error");
}
/*
#[tokio::main]: 절차적 매크로(Procedural Macro) 속성 — async fn main()을 일반 fn main()으로 자동 변환해 줌
변환된 main은 (1) Tokio 멀티스레드 런타임을 생성하고 (2) async 본문을 그 런타임에서 실행한 뒤 완료될 때까지 대기함
이 속성이 없으면 Rust 표준 main은 async를 직접 사용할 수 없음

Router::new(): 비어 있는 라우터를 생성 — 아직 등록된 경로(route)가 없는 상태
.route("/", get(hello_world)): 메서드 체이닝으로 경로를 등록
"/": URL 루트 경로와 매칭 (예: http://localhost:3001/)
get(hello_world): HTTP GET 메서드 요청이 들어오면 hello_world 핸들러를 호출하도록 연결
Axum은 핸들러의 인자 타입과 반환 타입을 컴파일 시점에 추론하여 타입 안전성을 보장함
let app: 위에서 구성한 라우터를 app 변수에 담아 이후 serve에 전달

tokio::net::TcpListener::bind(LISTEN_ADDR): 지정한 주소(LISTEN_ADDR)에 TCP 소켓을 바인딩하여 연결 대기 상태로 만듦
비동기 함수이므로 .await로 OS의 바인딩 작업이 끝날 때까지 현재 태스크를 일시 정지(suspend)함
반환 타입은 Result<TcpListener, Error> — 성공 시 Ok(listener), 실패 시 Err(예: 포트 이미 사용 중)
.expect("failed to bind TCP listener"): Err이면 에러 메시지와 함께 패닉(panic) — 학습용 데모에서는 단순 처리로 충분

println!(...): 서버가 정상적으로 바인딩되었음을 콘솔에 출력 (개발자 확인용)

axum::serve(listener, app): listener로 들어오는 TCP 연결을 받아 HTTP 요청으로 파싱하고, app 라우터에 맞는 핸들러로 분배(dispatch)
.await: 서버가 종료 신호(예: Ctrl+C)를 받거나 치명적 오류가 발생할 때까지 이 지점에서 대기
.expect("server error"): serve 중 치명적 오류 발생 시 패닉 — 데모 앱에서의 단순 에러 처리
*/
Rust
복사

Cargo.toml

[package]
name = "axum_helloworld"
version = "0.1.0"
edition = "2021"
description = "Minimal Axum Hello World web server"

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
Rust
복사

안녕하세요

•

관련 기술 문의와 R&D 공동 연구 사업 관련 문의는 “glory@keti.re.kr”로 연락 부탁드립니다.

Hello

•

For technical and business inquiries, please contact me at “glory@keti.re.kr”

한국전자기술연구원(KETI) - Researcher Card

KETI의 연구자에 대한 정보를 확인할 수 있습니다.

GloryKim - Overview

Kubeflow, Tensorflow, Front-End, IoTivity, Go, Microservice Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Jan Mon Wed Fri Created 14 commits in 4 repositories Opened their first pull request on GitHub in a private repository First pull request Opened 1 other pull request in 1 repository Reviewed 1 pull request in 1 repository GloryKim/Go 1 pull request Opened their first issue on GitHub in a private repository First issue 246 contributions in private repositories Jan 1 - Jan 26 You can't perform that action at this time.

Glory Kim

본 채널은 영상을 통한 수익창출을 하지않고 있음을 신고합니다. 본 채널은 제가 재직중인 직장에서 수행중인 프로젝트에 대한 홍보 및 외부 미팅시 참고자료로 사용하는 채널입니다. 본 영상을 통해서 기술이전 및 기술문의는 glory@keti.re.kr로 문의 부탁드립니다. 감사합니다.

김영광

Korea Electronics Technology Institute - 인용 횟수 36번 - AI - Health care - IoT