Skip to content

docs: include all feature introductions in the document#4035

Open
jujn wants to merge 2 commits intoalibaba:mainfrom
jujn:update_features_docs
Open

docs: include all feature introductions in the document#4035
jujn wants to merge 2 commits intoalibaba:mainfrom
jujn:update_features_docs

Conversation

@jujn
Copy link
Copy Markdown
Collaborator

@jujn jujn commented Mar 25, 2026

What this PR does / why we need it?

①修复 DisableStringArrayUnwrapping 特性说明不太准确;
②在文档中补充了所有遗漏介绍的特性;
③重构了文档中介绍特性的方式(分功能、分块介绍)

Summary of your change

Please indicate you've done the following:

  • Made sure tests are passing and test coverage is added if needed.
  • Made sure commit message follow the rule of Conventional Commits specification.
  • Considered the docs impact and opened a new docs issue or PR with docs changes if needed.

Copy link
Copy Markdown
Member

@wenshao wenshao left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: PR #4035 — docs: include all feature introductions in the document

Verdict: Request Changes — 1 Critical issue found, 3 Suggestions.


[Critical] SupportAutoType missing deprecation and security warning

Files: docs/features_cn.md (JSONReader.Feature table), docs/features_en.md (JSONReader.Feature table)

SupportAutoType is marked @Deprecated in the source code (JSONReader.java:6210), with javadoc stating "This feature is deprecated and should not be used in production code" and recommending AutoTypeBeforeHandler. The docs present it as a regular feature with no deprecation or security warning.

Since autoType is a known fastjson attack vector, this is security-relevant.

Suggested fix: Add a deprecation note in both CN and EN docs, e.g.:

  • CN: "(已弃用,不推荐在生产环境使用,建议使用 AutoTypeBeforeHandler)"
  • EN: " (Deprecated, not recommended for production use; use AutoTypeBeforeHandler instead)"

[Suggestion] JSONPath.Feature.DisableStringArrayUnwrapping javadoc not updated

File: core/src/main/java/com/alibaba/fastjson2/JSONPath.java:1646-1650

This PR fixed the same incorrect javadoc in JSONReader.java, but JSONPath.java still says "When enabled, JSON arrays containing a single string element will be unwrapped to just that string value" — the opposite of actual behavior.

Suggested fix: Apply the same javadoc correction used in JSONReader.java.


[Suggestion] MapSortField best practice recommendation is misleading

Files: docs/features_cn.md:272, docs/features_en.md:274

Best practices suggest using MapSortField to "maintain field order" / "keep field order", but the feature actually sorts keys alphabetically (not preserving insertion order) and is @Deprecated in favor of SortMapEntriesByKeys.

Suggested fix: Replace with SortMapEntriesByKeys and correct the description to "deterministic key ordering (e.g., signature verification)".


[Suggestion] FieldBased description typo in CN doc

File: docs/features_cn.md:47 (JSONReader.Feature table)

Description says "基于字段序列化" but JSONReader handles 反序列化 (deserialization).

Suggested fix: Change "序列化" to "反序列化".


— qwen3.6-plus via Qwen Code /review

@jujn
Copy link
Copy Markdown
Collaborator Author

jujn commented Apr 12, 2026

done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants