serde - Topics about IT

Rust는 Crate(크레이트) 단위로 코드와 라이브러리를 구성합니다.
크레이트는 Rust의 패키지 시스템에서 가장 작은 단위로, 우리가 Cargo.toml에 추가해서 사용하는 외부 라이브러리들도 모두 크레이트입니다.

크레이트의 기본 개념과 사용법, 외부 라이브러리를 프로젝트에 추가하고 사용하는 법, 그리고 버전 관리와 의존성에 대해 알아보겠습니다.

1. Crate란?

크레이트(Crate)는 하나의 컴파일 단위입니다.
두 가지로 나뉩니다:
– Binary Crate: main() 함수를 포함하고, 실행 가능한 프로그램이 됨
– Library Crate: 다른 크레이트에서 가져와 사용할 수 있는 재사용 가능한 코드 집합

예를 들어 우리가 사용하는 tokio, serde, rand 등은 모두 라이브러리 크레이트입니다.

2. Cargo로 외부 크레이트 사용하기

Rust 프로젝트는 Cargo라는 빌드 도구를 중심으로 관리됩니다.

가. Cargo.toml에 의존성(dependency) 추가

예를 들어 난수를 생성하는 rand 크레이트를 사용하려면, 프로젝트 루트의 Cargo.toml 파일의 dependencies 절에 다음과 같이 작성합니다.

처음에 버전을 0.8.0을 적었더니 버전이 0.9.1까지 있으니 여기서 선택하라고 화면이 표시됩니다.

[dependencies]
rand = "0.9.1"

이제 cargo build 또는 cargo run을 실행하면 자동으로 해당 크레이트가 다운로드되고 프로젝트에 포함됩니다.

나. 코드에서 사용하기

use rand::Rng;

fn main() {
    let mut rng = rand::rng();
    let n: u8 = rng.random_range(1..=10);
    println!("1부터 10 사이의 무작위 수: {}", n);
}

use rand::Rng;

Rng는 random_range() 같은 메서드를 제공하는 트레잇(trait)입니다.
이걸 use해야 random_range(…) 같은 메서드를 쓸 수 있습니다.

let mut rng = rand::rng();

최신 rand에서는 rand::rng()로 난수 생성기를 가져옵니다.
이전에는 rand::thread_rng()를 사용했지만, 그건 deprecated 되었고 이제는 rng()로 대체됩니다. rand 버전을 0.8로 하면 아래와 같은 에러가 발생합니다.

반환 타입은 여전히 내부적으로 ThreadRng입니다.

📝 의미:

“현재 스레드에서 사용할 난수 생성기를 가져와서 rng에 저장하라”

let n: u8 = rng.random_range(1..=10);

random_range(1..=10)은 1부터 10까지의 정수 중 무작위 값을 생성합니다.
inclusive range (..=)를 사용했으므로, 10도 포함됩니다.
반환되는 값은 u8 타입으로 명시적으로 지정했습니다.
random_range는 gen_range() 대신 사용되는 최신 방식입니다.

println!(“1부터 10 사이의 무작위 수: {}”, n);

생성된 난수 n을 콘솔에 출력합니다.
실행할 때마다 1~10 사이의 숫자가 무작위로 나옵니다.

3. 크레이트 문서 확인하기

모든 주요 크레이트는 문서를 잘 갖추고 있습니다.
https://docs.rs에서 크레이트 이름으로 검색하면 API 문서를 확인할 수 있습니다.

예: https://docs.rs/rand

문서에는 모듈 구조, 사용 예제, Trait 설명 등이 포함되어 있어 매우 유용합니다.

4. 크레이트 버전 지정

Cargo는 Semantic Versioning을 따릅니다.

rand = “0.9” → 0.9.x까지 자동 업데이트 (1.0은 제외)
rand = “=0.9.1” → 정확한 버전
rand = “>=0.9, <10.0” → 범위 지정

보통은 “0.9”와 같이 호환 가능한 최신 버전으로 표시하는 것이 일반적입니다.

5. 여러 크레이트 함께 사용하기

Rust 프로젝트는 여러 외부 크레이트를 함께 사용할 수 있습니다.

예:serde와 serde_json을 함께 사용하여 JSON을 파싱:

[Cargo.toml]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

[main.rs]

use serde::{Deserialize, Serialize};
use serde_json::Result;

#[derive(Serialize, Deserialize, Debug)]
struct Person {
    name: String,
    age: u8,
}

fn main() -> Result<()> {
    let data = r#"{"name": "홍길동", "age": 30}"#;
    let p: Person = serde_json::from_str(data)?;
    println!("{:?}", p);
    Ok(())
}

가. use 키워드

use serde::{Deserialize, Serialize};
use serde_json::Result;

Rust의 use 키워드는 코드에서 다른 모듈이나 라이브러리의 특정 항목(함수, 구조체, 열거형 등)을 현재 스코프(범위)로 가져와 사용하기 위해 사용됩니다. 이를 통해 코드를 더 간결하고 읽기 쉽게 만들 수 있습니다.
serde::{Deserialize, Serialize}: 구조체를 직렬화(Serialize) 또는 역직렬화(Deserialize) 하려면 이 트레잇이 필요합니다.
serde_json::Result: serde_json이 제공하는 Result 타입(Enum)을 사용합니다. 에러 처리를 쉽게 하기 위해 사용됩니다.

나. 구조체 정의

#[derive(Serialize, Deserialize, Debug)]
struct Person {
    name: String,
    age: u8,
}

[derive(…)]: 구조체에 자동으로 트레잇 구현을 추가합니다.
– Serialize: 구조체를 JSON으로 변환할 수 있게 함.
– Deserialize: JSON을 구조체로 변환할 수 있게 함.
– Debug: println!(“{:?}”, …)으로 구조체 내용을 출력할 수 있게 함.
Person 구조체 정의
– name: 문자열 타입
– age: u8(0~255 정수 타입)

다. main 함수

fn main() -> Result<()> {

반환 타입이Result<()>인 이유는 serde_json::from_str가 실패할 수 있기 때문입니다. 실패하면 에러를 리턴하고, 성공하면 Ok(())를 반환합니다.

라. JSON 문자열 → 구조체

let data = r#"{"name": "홍길동", "age": 30}"#;

r#”…#”는 raw string(원시 문자열) 문법입니다. 문자열 내부에 따옴표가 있어도 별도로 이스케이프할 필요가 없어 편리합니다.
{“name”: “홍길동”, “age”: 30}는 JSON 포맷 문자열입니다.

let p: Person = serde_json::from_str(data)?;

serde_json::from_str는 JSON 문자열을 파싱해서 Person 구조체로 변환합니다.
? 연산자는 실패 시 에러를 리턴하고, 성공 시 결과값을 반환합니다.

마. 구조체 출력

println!("{:?}", p);

구조체 p를 Debug 포맷으로 출력합니다. 결과는 예를 들어 다음과 같이 나옵니다.
Person { name: “홍길동”, age: 30 }

6. Crate.io에서 크레이트 찾기

외부 라이브러리는 모두 https://crates.io에서 검색할 수 있습니다.

인기 순, 다운로드 수, 최근 업데이트 순으로 정렬 가능
사용자 리뷰, 문서 링크, GitHub 코드도 확인 가능

예:

웹 요청 라이브러리: reqwest
비동기 실행기: tokio
CLI 도구 만들기: clap

7. 크레이트 네임스페이스(namespace)와 모듈(module)

크레이트를 임포트할 때는 보통 최상위 네임스페이스부터 시작합니다.

use regex::Regex; // regex 크레이트 내 Regex 타입 사용

내부 모듈에 접근할 땐 점(::)을 따라 구조를 확인합니다.

예:

use tokio::time::{sleep, Duration};

8. 주의사항

크레이트마다 버전이 다르면 충돌이 생길 수 있음 → Cargo가 자동으로 중복 조율
사용하지 않는 크레이트는 지워주는 게 좋음
일부 크레이트는 feature flag를 통해 기능을 선택적으로 활성화함

9. 정리

항목	설명
Crate	Rust 코드의 재사용 단위, 외부 라이브러리
Cargo.toml	의존성을 정의하는 설정 파일
crates.io	외부 크레이트 검색/다운로드 플랫폼
docs.rs	모든 크레이트의 공식 문서 모음 사이트
use	크레이트 또는 모듈에서 항목을 가져오는(import) 키워드

10. 마무리

Rust의 크레이트 생태계는 매우 강력하고 체계적입니다.
외부 라이브러리를 잘 활용하면, 코드의 양을 줄이고 품질을 높일 수 있습니다.
이제는 필요한 기능이 있다면 직접 구현하기보다 crates.io에서 검색해보는 것이 먼저입니다.

[태그:] serde

외부 라이브러리 사용법 (Crate 활용)