docs: include all feature introductions in the document#4035
docs: include all feature introductions in the document#4035jujn wants to merge 2 commits intoalibaba:mainfrom
Conversation
wenshao
left a comment
There was a problem hiding this comment.
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
AutoTypeBeforeHandlerinstead)"
[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
|
done. |
What this PR does / why we need it?
①修复 DisableStringArrayUnwrapping 特性说明不太准确;
②在文档中补充了所有遗漏介绍的特性;
③重构了文档中介绍特性的方式(分功能、分块介绍)
Summary of your change
Please indicate you've done the following: