Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Decouple document serialization from the portable API before preview

Đang mở
  • Có gì không ổn?
#116 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Sôi nổi
Công nghệ
java
Lĩnh vực
api, backend-api-design, databases

Hướng nghiên cứu

Bắt đầu bằng việc soạn thảo ADR/spec cho mô hình tài liệu trung lập, ranh giới codec và các quyết định về contract bắt buộc. Kiểm tra DocumentResult, QueryPage, ChangeEvent và khai báo dependency của multiclouddb-api, sau đó lần theo các ánh xạ provider và quá trình validation. Công việc được xem là hoàn tất khi đáp ứng các tiêu chí chấp nhận, bao gồm các bài kiểm thử conformance, benchmark và hướng dẫn migration.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Context

The portable API currently exposes Jackson-specific types and dependencies:

  • DocumentResult.document() returns Jackson ObjectNode.
  • ChangeEvent.data() returns Jackson JsonNode.
  • multiclouddb-api declares
    requires transitive com.fasterxml.jackson.databind.
  • Write inputs accept Map<String, Object> with behavior determined by an
    SDK-owned Jackson configuration.

microsoft/multiclouddb-sdk-for-java#105 additionally introduces a validation
pipeline that snapshots and traverses the input, serializes it with an internal
ObjectMapper, reparses it as a JsonNode, validates it again, converts it back
to a map, and then performs another provider-specific conversion. Caller
Jackson modules and serializer configuration are intentionally ignored.

Review discussion concluded that this creates both a public API compatibility
risk and avoidable serialization/allocation overhead. The serializer
architecture should be settled before further preview or GA release.

Goals

  • Remove serialization-implementation types from the portable public contract.
  • Allow customers to choose and independently configure their object serializer.
  • Keep Jackson available as a supported default adapter.
  • Keep portable validation and provider-native mapping under SDK control.
  • Avoid serialize/reparse/convert cycles before provider delegation.
  • Give Cosmos DB, DynamoDB, and Spanner one explicit value model for portable
    null, number, object, array, and binary behavior.

Proposed architectural direction

Separate two boundaries:

  1. Customer object mapping

    • A customer-extensible DocumentCodec/CodecProvider converts POJOs and
      generic Java types to and from the portable document model.
    • Codec instances have an explicit thread-safety and lifecycle contract.
    • Jackson support lives in a separate adapter artifact that can accept a
      customer-configured ObjectMapper.

  2. Portable document and provider mapping

    • multiclouddb-api owns an immutable Document/DocumentValue model with
      no Jackson dependency.
    • Provider modules convert this neutral model directly to Cosmos payloads,
      DynamoDB AttributeValue, and Spanner values.
    • Codec output remains subject to portable validation and provider
      capability checks.

Potential module layout:

  • multiclouddb-api: neutral document, patch, codec, error, and limit contracts
  • multiclouddb-core: standard conversion and validation without Jackson
  • multiclouddb-serializer-jackson: optional/default Jackson adapter
  • optional future Gson or JSON-B adapters
  • provider modules: neutral-document to provider-native conversion

azure-json-style token readers/writers may be evaluated as an internal
streaming implementation, but should not become public API until their
ownership, numeric, duplicate-key, limit, and error contracts are stable.

Required contract decisions

  • Missing field versus explicit null
  • Exact numeric representation and provider round-trip guarantees
  • Duplicate object-key handling
  • Binary representation and whether binary is part of the portable profile
  • Supported Java types for Map<String, Object> convenience overloads
  • Codec selection and precedence
  • Client-wide versus per-operation codec configuration
  • Thread safety and lifecycle
  • Depth, field-name, token-count, structural, and serialized-size limits
  • Stable path-aware errors without logging document contents
  • Read, query, change-feed, and partial-update result types

Acceptance criteria

  • No Jackson type appears in the neutral API signatures.
  • multiclouddb-api no longer requires Jackson transitively.
  • DocumentResult, QueryPage, and ChangeEvent use the same neutral document
    representation.
  • Arbitrary POJOs are accepted only through an explicit codec; unknown values
    are not silently stringified or passed through a hidden mapper.
  • The Jackson adapter supports a safe default and a caller-configured
    ObjectMapper.
  • Cosmos DB, DynamoDB, and Spanner map the neutral representation directly to
    native values.
  • Validation does not require the current
    snapshot → serialize → parse → convert → provider-convert cycle.
  • Benchmarks cover representative payload sizes, nesting, POJOs, allocation,
    latency, and limit-boundary behavior.
  • Conformance tests cover null versus absence, numeric fidelity, duplicate
    keys, binary policy, codec failures, and provider round trips.
  • Migration guidance is provided for existing ObjectNode/JsonNode callers.
  • Jackson advisories and supported adapter-version ranges remain part of normal
    dependency maintenance; the abstraction must not claim to eliminate CVE
    obligations.

Delivery plan

This should be a standalone prerequisite change based on canonical main, not
a branch stacked on microsoft/multiclouddb-sdk-for-java#105:

  1. Agree on an ADR/spec defining the stable public contract.
  2. Implement the neutral model, codec boundary, Jackson adapter, provider
    mappings, migration utilities, conformance, and benchmarks.
  3. Rebase microsoft/multiclouddb-sdk-for-java#105 onto the merged foundation.
  4. Reimplement partial-update validation and provider mapping using the neutral
    model.
  5. Do not merge or release #105 with the current serializer contract first.

Non-goals

  • Removing every internal use of Jackson
  • Claiming that a serializer abstraction eliminates dependency vulnerabilities
  • Allowing arbitrary serializer output to bypass portable validation
  • Exposing provider-native value types through the portable API
Ngôn ngữ chính
Java
Star
7
Fork
7
Merge trung bình
1 ngày 19 giờ
Pull request đã merge (30 ngày)
3

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoft/multiclouddb-sdk-for-java

Tất cả issue của microsoft/multiclouddb-sdk-for-java

Issue tương tự

Thêm issue về Java

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.