BSON과 함께 작업하기

개요

이 가이드에서는 Go 드라이버가 BSON 및 Go 유형 간의 변환을 처리하는 방법에 대해 배울 수 있습니다. Go 유형을 BSON으로 변환하는 프로세스를 마셜링(marshalling)이라고 하고, 그 반대의 과정을 언마셜링(unmarshalling)이라고 합니다.

다음 섹션에서는 Go 드라이버가 BSON 데이터를 표현하는 방법과 기본 마셜링 및 언마셜링 동작을 조정하는 방법에 대해 설명합니다.

데이터 유형

MongoDB는 쉽고 유연한 데이터 처리를 가능하게 하는 BSON이라는 바이너리 표현으로 문서를 저장합니다.

Go 드라이버는 BSON 데이터 작업을 위한 네 가지 주요 유형을 제공합니다:

• D: BSON 문서의 정렬된 표현(슬라이스)

• M: BSON 문서의 정렬되지 않은 표현(지도)

• A: BSON 배열의 정렬된 표현

• E: D 유형 내부의 단일 요소

다음 예시에서는 bson.D 유형을 사용하여 quantity 필드 값이 100보다 큰 문서와 일치하는 쿼리 필터를 구성하는 방법을 보여 줍니다.

filter := bson.D{{"quantity", bson.D{{"$gt", 100}}}}

Go 드라이버가 BSON 데이터를 처리하는 방법을 자세히 알아보려면 BSON 패키지 API 설명서를 참조하세요.

태그 작성

Go에서 구조체(struct)는 선언된 데이터 유형을 가진 데이터 필드의 컬렉션입니다. 구조체 필드에 첨부된 선택적 메타데이터인 구조체 태그를 사용해 구조체 필드의 기본 마셜링 및 언마셜링 동작을 수정할 수 있습니다. 구조체 태그의 가장 일반적인 용도는 구조체 필드에 해당하는 BSON 문서의 필드 이름을 지정하는 것입니다. 다음 표에서는 Go 드라이버에서 사용할 수 있는 추가적인 구조체 태그를 설명합니다.

만약 구조체 태그를 지정하지 않으면 Go 드라이버는 다음 규칙을 사용하여 구조체를 마셜링합니다:

1. 드라이버는 내보낸 필드를 마셜링 및 언마셜링 합니다.

2. 드라이버는 해당 구조체 필드에 소문자를 사용하여 BSON 키를 생성합니다.

3. 드라이버는 내장된 구조체 필드를 하위 문서로 마셜링합니다. 각 키는 필드 유형의 소문자입니다.

4. 드라이버는 포인터가 nil이 아닌 경우 포인터 필드를 기본 형식으로 마셜링합니다. 포인터가 nil이면 드라이버는 해당 포인터를 BSON null 값으로 마셜링합니다.

5. 언마셜링 시 Go 드라이버는 interface{} 유형의 필드에 다음 D/M 유형 매핑을 따릅니다. 드라이버는 interface{} 필드에 언마셜링된 BSON 문서를 D 유형으로 언마셜링합니다.

type Address struct {
       Street string
       City   string
       State  string
}
type Student struct {
       FirstName string  `bson:"first_name,omitempty"`
       LastName  string  `bson:"last_name,omitempty"`
       Address   Address `bson:"inline"`
       Age       int
}
coll := client.Database("db").Collection("students")
address1 := Address{ "1 Lakewood Way", "Elwood City", "PA" }
student1 := Student{ FirstName : "Arthur", Address : address1, Age : 8}
_, err = coll.InsertOne(context.TODO(), student1)

{
  "_id" : ObjectId("..."),
  "first_name" : "Arthur",
  "street" : "1 Lakewood Way",
  "city" : "Elwood City",
  "state" : "PA",
  "age" : 8
}

type Address struct {
       Street string
       City   string
       State  string
}
type Student struct {
       FirstName string
       LastName  string
       Address   Address
       Age       int
}
coll := client.Database("db").Collection("students")
address1 := Address{ "1 Lakewood Way", "Elwood City", "PA" }
student1 := Student{ FirstName : "Arthur", Address : address1, Age : 8}
_, err = coll.InsertOne(context.TODO(), student1)

{
  "_id" : ObjectId("..."),
  "firstname" : "Arthur",
  "lastname" : "",
  "address": {
               "street" : "1 Lakewood Way",
               "city" : "Elwood City",
               "state" : "PA"
             },
  "age" : 8
}

BSON 옵션

BSON 옵션을 지정하여 Client 인스턴스의 마셜링 및 링 언마셜동작을 조정할 수 있습니다. Client에 BSON 옵션을 설정하려면 BSONOptions 인스턴스를 생성하고 구성합니다.

이 예에서는 다음 조치를 수행합니다.

• 다음 설정을 구성하여 BSONOptions 인스턴스를 만듭니다:

  • UseJSONStructTags 필드를 true로 설정하여 "bson" 구조체 태그가 지정되지 않은 경우 드라이버가 "json" 구조체 태그를 사용하도록 지시합니다.

  • NilSliceAsEmpty 필드를 true로 설정하여 드라이버가 nil 고(Go) 슬라이스를 빈 BSON 배열로 마셜링하도록 지시합니다.

• BSONOptions 인스턴스를 SetBSONOptions() 헬퍼 메서드에 전달해 ClientOptions 인스턴스를 지정합니다.

• 지정된 BSON 마셜링 및 언마셜링 동작을 적용하기 위해 Client를 만듭니다.

bsonOpts := &options.BSONOptions {
    UseJSONStructTags: true,
    NilSliceAsEmpty: true,
}
clientOpts := options.Client().
    ApplyURI("<connection string>").
    SetBSONOptions(bsonOpts)
client, err := mongo.Connect(context.TODO(), clientOpts)

Unmarshalling

FindOne 방법의 결과 또는 *mongo.Cursor 인스턴스에 Decode() 을(를) 사용하여 BSON 문서를 언마샬링(unmarshalling)할 수 있습니다.

Decode() 메서드는 다음 값 중 하나를 포함하는 error 유형을 반환합니다.

• nil 문서가 쿼리와 일치하고 문서를 검색하고 언마셜링하는 데 오류가 없는 경우.

• 드라이버가 문서를 검색했지만 결과를 언마셜링하지 못한 경우 Decode() 메서드는 언마셜링 오류를 반환합니다.

• FindOne() 메서드를 실행하는 동안 문서를 검색하는 데 오류가 발생한 경우, 해당 오류는 Decode() 메서드로 전파되고 Decode() 메서드는 오류를 반환합니다.

FindOne() 메서드에서 반환된 SingleResult 유형에서 사용하는 경우 Decode()는 쿼리 필터와 일치하는 문서가 없으면 ErrNoDocuments 오류를 반환할 수도 있습니다.

다음 예에서는 Decode() 메서드를 사용하여 간단한 FindOne() 작업의 결과를 역마샬링하고 읽는 방법을 보여줍니다.

coll := client.Database("db").Collection("students")
filter := bson.D{{"age", 8}}
var result bson.D
err := coll.FindOne(context.TODO(), filter).Decode(&result)
fmt.Println(result)

또한 Cursor 유형은 커서에 저장된 모든 문서를 동시에 배열로 언마셜링하는 All() 메서드를 사용합니다.

bson 패키지에는 BSON으로 인코딩된 []byte 유형의 데이터를 처리하는 Marshal() 및 Unmarshal() 메서드 패밀리가 포함되어 있습니다.

다음 코드는 bson 패키지의 메서드를 사용하여 BSON을 다시 사용자 정의 구조체로 언마셜링하는 방법을 보여줍니다.

type Item struct {
   Category string
   Quantity int32
}
doc, err := bson.Marshal(bson.D{{"category", "plate"}, {"quantity", 6}})
var test Item
err = bson.Unmarshal(doc, &test)
fmt.Printf("Unmarshalled Struct:\n%+v\n", test)

Cursor 유형과 함께 사용되는 마샬링 및 언마셜링 메서드에 대해 자세히 알아보려면 커서 API 문서를 참조하세요.

bson 패키지의 마샬링 및 언마샬링 메서드에 대해 자세히 알아보려면 bson API 문서를 참조하세요.