โครงสร้างโปรเจกต์
ถ้าคุณเคยเปิดโปรเจกต์ใหม่แล้วไม่รู้ว่าจะวางไฟล์ใหม่ของคุณตรงไหน คุณคงตระหนักดีว่าโครงสร้างไดเรกทอรีมีความสำคัญเพียงใด ฟังดูเหมือนเรื่องเล็กน้อย แต่ผมเคยเห็นหลายทีมต้องเสียเวลาไปหลายชั่วโมงกับการถกเถียงว่าโค้ดควรจัดวางไว้ตรงไหน และเคยเห็นโปรเจกต์ที่ทุกอย่างถูกยัดรวมกันไว้ในไดเรกทอรี src/ ขนาดมหึมาเพียงแห่งเดียวเพราะไม่มีใครกำหนดแนวทางไว้ตั้งแต่เริ่มต้น ซึ่งไม่ใช่เรื่องน่าอภิรมย์เลยแม้แต่น้อย
ไม่มีวิธีจัดโครงสร้างเว็บแอปพลิเคชัน Rust ที่ถูกต้องสมบูรณ์แบบเพียงวิธีเดียว แต่มีแพตเทิร์นที่พิสูจน์แล้วว่าใช้งานได้ผลดีเยี่ยมในทางปฏิบัติ ในบทนี้เราจะมาดู 2 รูปแบบหลัก ได้แก่ โครงสร้างแบบเครตเดียว (single-crate) สำหรับโปรเจกต์ขนาดเล็กถึงขนาดกลาง และโครงสร้างแบบเวิร์กสเปซ (workspace) สำหรับระบบที่เติบโตขึ้น ทั้งสองรูปแบบต่างตั้งอยู่บนหลักการพื้นฐานเดียวกัน เพียงแค่ปรับเปลี่ยนตามขนาดและสเกลของระบบเท่านั้น
หลักการ
ก่อนที่เราจะไปดูผังโครงสร้างไดเรกทอรีในรายละเอียด ผมขอสรุปแนวคิดหลักที่อยู่เบื้องหลังโครงสร้างเหล่านี้ให้ฟังก่อนครับ
จัดกลุ่มตามเลเยอร์สถาปัตยกรรมก่อน แล้วค่อยจัดตามความรับผิดชอบ (concern) ภายในแต่ละเลเยอร์ การแบ่งสัดส่วนหลักของเราคือระหว่าง api, domain, และ infra ซึ่งเป็นการบังคับใช้กฎของ dependency (Dependency Rule) ตามที่เราได้พูดถึงไปก่อนหน้านี้ ภายในแต่ละเลเยอร์ เราจะจัดโมดูลตามหน้าที่ความรับผิดชอบ (เช่น แฮนด์เลอร์, โมเดล, รีพอสิทอรี) ขอบอกตามตรงว่าแนวทางนี้หมายความว่า เวลาที่คุณพัฒนาฟีเจอร์เกี่ยวกับผู้ใช้ คุณอาจต้องเปิดสลับไปมาระหว่าง api/handlers/users.rs, domain/models/user.rs และ infra/repositories/user_repo.rs ซึ่งนี่คือข้อแลกเปลี่ยน (trade-off) ในทางปฏิบัติ เมื่อโค้ดเบสขยายใหญ่ขึ้น บางทีมอาจพบว่าการจัดโครงสร้างภายในเลเยอร์ตามแนวฟีเจอร์ (feature slice) เช่น domain/users/model.rs, domain/users/service.rs สะดวกกว่าการจัดตามบทบาทหน้าที่ ซึ่งไม่ว่าจะเลือกแบบใดก็ใช้ได้ทั้งสิ้น สิ่งที่สำคัญที่สุดคือขอบเขตระหว่างแต่ละเลเยอร์จะต้องเด่นชัดและไม่คลุมเครือ
บังคับทิศทางของ dependency (Enforce dependency direction) นี่คือหลักการสำคัญที่สุด ดีเพนเดนซีควรไหลเข้าสู่แกนกลางเสมอ นั่นคือจากเลเยอร์ HTTP มุ่งหน้าเข้าหาเลเยอร์โดเมน โมดูลโดเมนของคุณจึงต้องไม่มีการ import สิ่งใดจาก api หรือ infra เลยแม้แต่อย่างเดียว ความเป็นอิสระนี้เองที่ทำให้ตรรกะทางธุรกิจของคุณสามารถนำไปใช้งานที่อื่นได้ง่าย (portable) และทดสอบแยกเดี่ยวได้อย่างแท้จริง ในโครงสร้างแบบเครตเดียว คุณต้องบังคับใช้ผ่านข้อตกลงร่วมกันและการตรวจทานโค้ด (code review) ซึ่งต้องอาศัยวินัยและความไว้ใจในทีม แต่หากเป็นเวิร์กสเปซ Cargo จะช่วยบังคับผ่านกราฟดีเพนเดนซีของเครตให้อัตโนมัติ ซึ่งแน่นอนว่าปลอดภัยกว่ามาก
ทำให้ main.rs บางที่สุด (Keep main.rs thin) จุดเริ่มต้นการทำงาน (entry point) ของคุณควรทำเพียง 3 หน้าที่หลักเท่านั้น ได้แก่: โหลดการตั้งค่า, ประกอบแอปพลิเคชัน (เชื่อมต่อ wiring ดีเพนเดนซีต่างๆ เข้าด้วยกัน) และสตาร์ตเซิร์ฟเวอร์ เพียงเท่านี้จริงๆ หาก main.rs ของคุณเริ่มยาวขึ้นเรื่อยๆ นั่นเป็นสัญญาณเตือนว่าถึงเวลาย้ายตรรกะการเตรียมระบบ (setup logic) ไปไว้ในโมดูลเฉพาะของตัวเองแล้ว
ใช้ระบบการควบคุมการเข้าถึงเพื่อกำหนดขอบเขต กลไกการกำหนดสิทธิ์การเข้าถึงโมดูลของ Rust (pub, pub(crate), pub(super) และค่าเริ่มต้นที่เป็นแบบ private) คือเครื่องมือทรงพลังในการควบคุมว่าโค้ดส่วนใดสามารถเข้าถึงสิ่งใดได้บ้าง จงเปิดเผยเฉพาะสิ่งที่จำเป็นต้องเป็น public ผ่านไฟล์ mod.rs เท่านั้น และเก็บรายละเอียดการทำงานภายใน (implementation details) ไว้เป็น private หากคุณคุ้นเคยกับโลก JavaScript ลองนึกภาพแพตเทิร์น barrel-export แต่ถูกบังคับใช้อย่างเข้มงวดโดยคอมไพเลอร์ แทนที่จะต้องพึ่งพาเพียงวินัยหรือเจตนาที่ดีของนักพัฒนา
โครงสร้างเครตเดียว
นี่คือรูปแบบที่ผมเลือกใช้สำหรับโปรเจกต์ส่วนใหญ่ เพราะให้การแยกเลเยอร์ที่สะอาดหมดจดโดยไม่ต้องแบกรับภาระการดูแลหลายเครต และคุณยังสามารถต่อยอดไปเป็นเวิร์กสเปซในภายหลังได้อย่างราบรื่นหากระบบเติบโตขึ้น เรามาดูโครงสร้างกันครับ
my-app/
├── Cargo.toml
├── .env.example
├── migrations/
│ ├── 20240101_create_users.sql
│ └── 20240102_create_posts.sql
├── src/
│ ├── main.rs
│ ├── lib.rs
│ ├── config.rs
│ ├── error.rs
│ │
│ ├── domain/
│ │ ├── mod.rs
│ │ ├── models/
│ │ │ ├── mod.rs
│ │ │ ├── user.rs
│ │ │ └── post.rs
│ │ ├── errors.rs
│ │ ├── ports/ # Trait definitions (optional, for trait-based abstractions)
│ │ │ └── user_repository.rs
│ │ └── services/
│ │ ├── mod.rs
│ │ ├── user_service.rs
│ │ └── post_service.rs
│ │
│ ├── infra/
│ │ ├── mod.rs
│ │ ├── db.rs
│ │ └── repositories/
│ │ ├── mod.rs
│ │ ├── user_repo.rs
│ │ └── post_repo.rs
│ │
│ └── api/
│ ├── mod.rs
│ ├── routes.rs
│ ├── state.rs
│ ├── handlers/
│ │ ├── mod.rs
│ │ ├── health.rs
│ │ ├── users.rs
│ │ └── posts.rs
│ ├── extractors/
│ │ ├── mod.rs
│ │ ├── validated_json.rs
│ │ └── auth_user.rs
│ ├── middleware/
│ │ ├── mod.rs
│ │ └── auth.rs
│ └── dtos/
│ ├── mod.rs
│ ├── user_dto.rs
│ └── post_dto.rs
│
├── tests/
│ ├── common/
│ │ ├── mod.rs
│ │ └── test_app.rs
│ └── api/
│ ├── health_test.rs
│ └── users_test.rs
มาดูกันว่าแต่ละส่วนทำหน้าที่อะไร
main.rs และ lib.rs
ไฟล์ main.rs คือจุดเริ่มต้นการทำงานของแอปพลิเคชัน ทำหน้าที่โหลดการตั้งค่า, เริ่มต้นระบบ tracing, สร้างตัวแอปพลิเคชัน และเปิดเซิร์ฟเวอร์เพื่อรอรับคำขอ หน้าที่มีเพียงเท่านี้ และควรคงความเรียบง่ายนี้ไว้เสมอ
use my_app::{config::Config, create_app, observability};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::from_env()?;
observability::init_tracing(&config.log_level);
let app = create_app(config.clone()).await?;
let addr = format!("0.0.0.0:{}", config.port);
let listener = tokio::net::TcpListener::bind(&addr).await?;
tracing::info!("listening on {}", listener.local_addr()?);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal()) // defined in the Deployment chapter
.await?;
Ok(())
}
ไฟล์ lib.rs ทำหน้าที่ประกาศโมดูลต่างๆ และเตรียมฟังก์ชัน create_app ไว้ให้ใช้งาน ซึ่งฟังก์ชันนี้จะถูกเรียกใช้โดยชุดการทดสอบการผสาน (integration tests) ด้วยเช่นกัน นั่นหมายความว่าการทดสอบของคุณจะทดสอบกระบวนการเชื่อมต่อ (wiring) แบบเดียวกับที่ใช้บนระบบ production ทุกประการ ผมชื่นชอบแพตเทิร์นนี้มาก เพราะทำให้มั่นใจได้ว่าจะไม่มีเส้นทางการเตรียมระบบ “สำหรับการทดสอบโดยเฉพาะ” ที่อาจมีพฤติกรรมเบี่ยงเบนไปจากระบบจริงโดยที่เราไม่รู้ตัว
#![allow(unused)]
fn main() {
pub mod api;
pub mod config;
pub mod domain;
pub mod error;
pub mod infra;
pub mod observability;
use axum::Router;
use config::Config;
pub async fn create_app(config: Config) -> anyhow::Result<Router> {
let pool = infra::db::create_pool(
config.database_url.expose_secret()
).await?;
sqlx::migrate!("./migrations").run(&pool).await?;
let state = AppState::new(config, pool);
let router = api::routes::router(state);
Ok(router)
}
}
โมดูล domain
นี่คือหัวใจของแอปพลิเคชันของคุณ และต้องไม่มี dependency ใดๆ ต่อ Axum, SQLx หรือเฟรมเวิร์กภายนอกเลยแม้แต่ตัวเดียว เครตภายนอกที่จำเป็นมักมีเพียง serde (สำหรับการ serialize ข้อมูล), thiserror (สำหรับสร้างชนิดข้อมูลข้อผิดพลาด) และเครตยูทิลิตี้พื้นฐานอย่าง uuid และ chrono เท่านั้น แม้จะดูเข้มงวดและมีข้อจำกัด แต่ข้อจำกัดนี้นี่เองที่ช่วยปกป้องความบริสุทธิ์ของเลเยอร์นี้ให้ทำหน้าที่ตามที่ควรจะเป็นอย่างแท้จริง
ไดเรกทอรี models/ บรรจุเอนทิตีของโดเมนและ value object ซึ่งเป็นชนิดข้อมูลที่จำลองแนวคิดหลักที่ระบบทำงานด้วย ส่วน services/ คือที่อยู่ของตรรกะทางธุรกิจ (business logic) ซึ่งก็คือโค้ดที่เข้ามาจัดการและประมวลผลโมเดลเหล่านั้น และ errors.rs จะทำหน้าที่กำหนดชนิดข้อมูลข้อผิดพลาดเฉพาะของโดเมน
แล้วถ้าเลเยอร์โดเมนจำเป็นต้องติดต่อกับโลกภายนอกล่ะ? ไม่ว่าจะเป็นฐานข้อมูล, บริการส่งอีเมล หรือ API ภายนอก? คำตอบคือโดเมนจะกำหนดสัญญาข้อตกลงผ่าน trait ไว้ในไดเรกทอรี ports/ ส่วนโค้ดที่นำ trait เหล่านั้นไปอิมพลีเมนต์ใช้งานจริงจะไปอยู่ที่เลเยอร์ infra เราจะได้เห็นตัวอย่างแพตเทิร์นนี้อย่างละเอียดในบทต่อๆ ไป
โมดูล infra
นี่คือที่อยู่ของโค้ดที่จัดการฐานข้อมูล db.rs ดูแลการสร้าง connection pool และ repositories/ จะบรรจุการอิมพลีเมนต์จริง (concrete implementation) ของ repository trait ต่างๆ ที่โดเมนได้กำหนดไว้
แต่ละ struct ในรีพอสิทอรีจะถือการอ้างอิงไปยัง connection pool และอิมพลีเมนต์ trait ที่ตรงกันจากเลเยอร์โดเมน หน้าที่ของมันคือทำตัวเป็นสะพานเชื่อม แปลงข้อมูลระหว่างชนิดข้อมูลแถว (row type) ของฐานข้อมูลกับโมเดลของโดเมน เปรียบเสมือนล่ามที่เชี่ยวชาญทั้งภาษา SQL และภาษาโดเมนของ Rust
โมดูล api
นี่คือเลเยอร์ที่ผูกพันกับ Axum โดยตรง เข้าใจและรับรู้แนวคิดของ HTTP อย่างสมบูรณ์ เช่น รหัสสถานะ (status code), บอดี้ JSON, ส่วนหัว (header) และมิดเดิลแวร์ เลเยอร์นี้ต้องไม่มีตรรกะทางธุรกิจปะปนอยู่ หากคุณพบว่าตัวเองกำลังเขียนคำสั่ง if เพื่อตรวจสอบเงื่อนไขทางธุรกิจภายในแฮนด์เลอร์ นั่นคือสัญญาณว่าคุณควรย้ายโค้ดส่วนนั้นไปยังเซอร์วิสได้แล้ว
ฟังก์ชันใน handlers/ จะต้องบางและกระชับ มีหน้าที่เพียงสกัดข้อมูลจากคำขอ เรียกใช้เมธอดของเซอร์วิส และส่งผลลัพธ์กลับเป็นการตอบกลับ ผมชอบให้ฟังก์ชันเหล่านี้สั้นที่สุดเท่าที่จะทำได้ ในอุดมคติคือไม่ควรเกิน 20 บรรทัด ส่วน dtos/ จะทำหน้าที่กำหนดโครงสร้างของข้อมูลคำขอและการตอบกลับ (request/response bodies) โดยแยกขาดจากโมเดลของโดเมน เพื่อให้สัญญาของ API (API contract) สามารถปรับเปลี่ยนได้อย่างอิสระโดยไม่ขึ้นอยู่กับโครงสร้างข้อมูลภายใน ส่วน extractors/ จะเก็บ extractor แบบกำหนดเองของ Axum เช่น ValidatedJson หรือ AuthUser (ซึ่งเราจะร่วมกันสร้างในบทต่อๆ ไป) และ middleware/ จะรวบรวมมิดเดิลแวร์ของ Tower ที่สร้างขึ้นเฉพาะสำหรับโปรเจกต์
สุดท้าย ไฟล์ routes.rs จะทำหน้าที่ประกอบเราเตอร์ขึ้นมา โดยนำกลุ่มเส้นทางแต่ละกลุ่มมารวมเข้าด้วยกันและติดตั้งเลเยอร์มิดเดิลแวร์ให้พร้อมใช้งาน
โครงสร้างเวิร์กสเปซ
เมื่อถึงจุดหนึ่ง โปรเจกต์ของคุณอาจเติบโตจนเวลาที่ใช้ในการคอมไพล์เริ่มส่งผลกระทบต่อความเร็วในการพัฒนา หรือระบบอาจมีหลายทีมที่ต้องรับผิดชอบคนละส่วนของระบบ นั่นคือจังหวะที่ผมแนะนำให้เริ่มพิจารณาแบ่งโปรเจกต์ออกเป็น Cargo workspace เวิร์กสเปซจะช่วยบังคับใช้กฎของ dependency ในระดับเครต: หากเครต domain ไม่ได้ประกาศ sqlx ไว้ใน Cargo.toml ก็จะไม่มีใครสามารถเผลอ import มันเข้ามาใช้งานในโดเมนได้อย่างแน่นอน เพราะคอมไพเลอร์จะคอยตรวจจับให้เสมอ
my-app/
├── Cargo.toml # [workspace] definition
├── .env.example
├── migrations/
│
├── crates/
│ ├── domain/
│ │ ├── Cargo.toml # deps: serde, thiserror, uuid, chrono
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── models/
│ │ ├── services/
│ │ ├── ports/ # trait definitions
│ │ └── errors.rs
│ │
│ ├── infra/
│ │ ├── Cargo.toml # deps: domain, sqlx, reqwest, etc.
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── postgres/
│ │ ├── redis/
│ │ └── email/
│ │
│ ├── api/
│ │ ├── Cargo.toml # deps: domain, infra, axum, tower, tower-http
│ │ └── src/
│ │ ├── main.rs
│ │ ├── lib.rs
│ │ ├── routes/
│ │ ├── handlers/
│ │ ├── middleware/
│ │ ├── extractors/
│ │ └── dtos/
│ │
│ └── shared/
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── config.rs
│ └── observability.rs
ไฟล์ Cargo.toml ที่ระดับรูตจะทำหน้าที่กำหนดขอบเขตของเวิร์กสเปซ และที่สำคัญไม่แพ้กันคือ การกำหนดเวอร์ชันของ dependency ส่วนกลางร่วมกัน นี่คือหนึ่งในฟีเจอร์ของ Cargo ที่ผมชื่นชอบมากที่สุด เพราะช่วยป้องกันไม่ให้เกิดปัญหาที่มี serde 3 เวอร์ชันแตกต่างกันกระจายตัวอยู่ในแต่ละเครตของคุณ:
[workspace]
members = ["crates/*"]
resolver = "2"
[workspace.dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "uuid", "chrono", "migrate"] }
axum = { version = "0.8", features = ["macros"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["cors", "compression-gzip", "trace", "timeout", "request-id", "limit"] }
thiserror = "2"
anyhow = "1"
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
จากนั้นแต่ละเครตจะสืบทอดเวอร์ชันส่วนกลางเหล่านี้ผ่านการตั้งค่า .workspace = true:
# crates/domain/Cargo.toml
[package]
name = "domain"
[dependencies]
serde.workspace = true
thiserror.workspace = true
uuid.workspace = true
chrono.workspace = true
# Note: no axum, no sqlx
จุดเด่นสำคัญที่สุดของแนวทางนี้คือ Cargo จะทำหน้าที่เป็นเกราะป้องกันการละเมิดสถาปัตยกรรมให้คุณ หากใครในทีมพยายามเพิ่มโค้ด import SQLx ในเครตโดเมน ตัวบิลด์จะล้มเหลวทันทีเนื่องจากไม่มี sqlx อยู่ในรายการ dependency ของเครตนั้น ผมเคยเห็นบั๊กประเภท “เผลอผูกโดเมนเข้ากับฐานข้อมูลโดยไม่รู้ตัว” มามากพอ จนรู้สึกซาบซึ้งทุกครั้งที่คอมไพเลอร์ช่วยดักจับความผิดพลาดเหล่านี้ให้ตั้งแต่แรก ซึ่งเป็นการรับประกันที่หนักแน่นและเชื่อถือได้มากกว่าการพึ่งพาเพียงการตรวจทานโค้ด (code review) เพียงอย่างเดียว
เมื่อไหร่ควรเลือกแบบไหน
คำแนะนำของผม: เริ่มต้นด้วยโครงสร้างแบบเครตเดียว (single-crate) ก่อนเสมอ เพราะแนวทางนี้ให้ประโยชน์เชิงโครงสร้างในการแบ่งแยกโค้ดอย่างสะอาดหมดจดครบถ้วน โดยไม่ต้องแบกรับภาระความยุ่งยากในการบริหารจัดการเวิร์กสเปซ คุณสามารถแยกเป็นเวิร์กสเปซในภายหลังเมื่อมีความจำเป็นเกิดขึ้นจริงได้อย่างไม่ยากเย็น เพราะขอบเขตของแต่ละโมดูลถูกวางไว้อย่างเป็นระเบียบตั้งแต่แรกอยู่แล้ว
แล้วเมื่อใดที่คุณควรพิจารณาย้ายไปใช้เวิร์กสเปซจริงๆ? จากประสบการณ์ของผม คือเมื่อคุณเริ่มเผชิญกับสถานการณ์ข้อใดข้อหนึ่งต่อไปนี้:
- เวลาที่ใช้ในการคอมไพล์เริ่มนานเกินไปจนกระทบต่อประสิทธิภาพการทำงาน และคุณต้องการให้กระบวนการบิลด์แบบเพิ่มหน่วย (incremental build) คอมไพล์เฉพาะส่วนที่มีการเปลี่ยนแปลงเท่านั้น
- มีหลายทีมทำงานร่วมกันในแต่ละส่วนของระบบ และคุณต้องการสร้างเส้นแบ่งขอบเขตที่เด็ดขาดระหว่างขอบเขตความรับผิดชอบของแต่ละทีม
- คุณต้องการเผยแพร่บางเครตแยกเป็นอิสระ (เช่น ไลบรารีโดเมนส่วนกลางที่ถูกเรียกใช้โดยหลากหลายเซอร์วิส)
- โปรเจกต์เติบโตจนไดเรกทอรี
src/เพียงแห่งเดียวเริ่มรู้สึกเทอะทะและจัดการได้ยาก
โครงสร้างเวิร์กสเปซยังทำงานได้อย่างยอดเยี่ยมกับสถาปัตยกรรมแบบ monorepo ซึ่งมีหลากหลายเซอร์วิส (เช่น API เซิร์ฟเวอร์, เวิร์กเกอร์เบื้องหลัง, เครื่องมือ CLI) ที่ใช้โค้ดโดเมนและโค้ดอินฟราสตรักเจอร์ชุดเดียวกัน เราจะมาเจาะลึกรูปแบบการตั้งค่าลักษณะนี้ในบทต่อๆ ไปเมื่อพูดถึงเรื่องงานเบื้องหลัง (background jobs)