wasm-pack과 React로 Rust를 WASM으로 변환하기

표준 러스트-WASM 작업 흐름은 두 가지 도구를 사용합니다. wasm-pack은 빌드를 조정하여 러스트를 WASM으로 컴파일하고 wasm 바인드젠을 실행하며 패키지 관리자용 패키지를 생성합니다. wasm-bindgen은 적절한 형식 처리를 통해 러스트 함수를 일반 JavaScript 함수처럼 호출할 수 있게 하는 JavaScript 바인딩을 생성합니다.

#[wasm_bindgen] 특성은 러스트 함수, 구조체 및 메서드를 JavaScript로 내보낼 대상으로 표시합니다. 이 특성이 없으면 함수는 WASM으로 컴파일되지만 JavaScript에서 액세스할 수 없습니다. 함수에 #[wasm_bindgen] 특성을 지정하면 wasm 바인드젠이 인수와 반환 값의 변환을 처리하는 JavaScript 연결 코드를 생성합니다.

최소한으로 내보낸 러스트 함수는 다음과 같습니다: use wasm_bindgen::prelude::*; #[wasm_bindgen] pub fn add(a: u32, b: u32) -> u32 { a + b }. 이 함수는 부호 없는 32비트 정수 두 개를 받아 하나를 반환합니다. wasm 바인드젠은 이 함수를 숫자 인수로 호출하고 숫자 결과를 반환하는 JavaScript 코드를 생성합니다.

러스트 크레이트 디렉터리에서 wasm-pack build --target web을 실행하십시오. 이 명령은 러스트 코드를 WASM으로 컴파일하고, wasm-bindgen을 실행해 JavaScript 바인딩을 생성하며, pkg/ 디렉터리를 출력합니다. 이 디렉터리에는 .wasm 바이너리, JavaScript 연결 모듈 및 TypeScript 형식 정의가 들어 있습니다.

생성된 모듈을 리액트 컴포넌트로 가져오십시오: import init, { add } from '../pkg/my_lib'. init 함수가 WASM 바이너리를 로드하고 인스턴스화하므로 useEffect에서 한 번 호출하십시오. 초기화가 끝나면 내보낸 함수를 직접 호출합니다: const result = add(2, 3).

기본 숫자를 넘어서는 복합 데이터의 경우 wasm 바인드젠은 js_sys::Array(JavaScript 배열), js_sys::Object(JavaScript 객체), wasm_bindgen::JsValue(모든 JavaScript 값)를 제공합니다. 이러한 형식을 사용하면 러스트 함수가 JavaScript 배열과 객체를 받아 반환할 수 있지만, 기본 형식보다 직렬화 비용이 더 많이 발생합니다.

핵심 성능 원칙은 데이터를 WASM 메모리에 유지하고 모든 계산을 그 안에서 수행하는 것입니다. 데이터를 한 번 전달하고 계산한 뒤 최종 결과만 반환하십시오. 각 단계마다 WASM 경계를 반복해서 가로질러 데이터를 전송하는 패턴은 피하십시오. 경계를 통과할 때마다 발생하는 오버헤드는 작지만, 성능에 민감한 반복문에서는 누적됩니다.

serde-wasm-bindgen 크레이트를 사용하면 Serde를 통해 Rust 구조체를 JavaScript 객체로 직렬화하거나 그 반대로 변환할 수 있습니다. 구조체에 #[derive(Serialize, Deserialize)]를 어노테이션으로 추가하고 serde_wasm_bindgen::to_value()와 from_value()를 사용하십시오. 복잡한 구조화 데이터를 전달할 때 사용하는 표준적인 방법입니다.

장시간 실행되는 WASM 계산은 실행 중인 스레드를 차단합니다. WASM을 Web Worker에서 실행하여 React의 메인 스레드를 계속 사용할 수 있게 하십시오. WASM 모듈을 초기화하고 메시지를 처리하는 Worker 파일을 만드십시오. postMessage를 통해 워커로 데이터를 보내고, message 이벤트를 통해 결과를 받은 다음, 그 결과로 React 상태를 업데이트하십시오.

wasm-pack은 내보낸 모든 함수와 타입에 대한 TypeScript 선언 파일(.d.ts)을 자동으로 생성합니다. 따라서 React TypeScript 프로젝트에서 Rust 함수를 호출할 때 완전한 타입 안전성을 확보할 수 있습니다. 생성된 타입은 Rust 함수 시그니처(add(a: number, b: number): number)를 반영하므로 IDE 자동 완성이 올바르게 작동합니다.

WASM 바이너리는 최적화 후 일반적으로 100kb-2MB입니다. 크기를 적극적으로 최적화하려면 Cargo.toml의 릴리스 프로필에 opt-level = "z"를 설정하여 wasm-opt를 wasm-pack 빌드에서 활성화하십시오. WASM 파일은 Content-Type: application/wasm으로 제공하고 HTTP/2를 활성화하여 브라우저가 바이너리를 효율적으로 스트리밍하도록 하십시오.

Rust 코드에서 #[wasm_bindgen] 속성은 어떤 용도로 사용되나요?

wasm-pack build --target web은 Rust를 WASM으로 컴파일하고 wasm-bindgen을 통해 JavaScript 바인딩을 생성합니다. 내보낼 함수에 #[wasm_bindgen]을 어노테이션으로 추가하십시오. React에서 init과 내보낸 함수를 가져오고, useEffect에서 init()을 호출한 다음 함수를 일반적인 JavaScript 함수처럼 호출하십시오. 복잡한 구조체 직렬화에는 serde-wasm-bindgen을 사용하십시오. 긴 계산은 Web Worker에서 WASM을 실행하여 React의 메인 스레드를 계속 사용할 수 있게 하십시오.