为何Javadoc未记录部分理应存在的字段？以LocalTime为例

• 封装原则的核心体现：Java面向对象设计的核心原则之一就是封装，LocalTime作为Java时间API的核心类，刻意将内部状态（比如秒、纳秒相关的存储逻辑）隐藏，仅对外暴露getSecond()、getNano()这类访问方法。Javadoc的定位是提供类的使用接口说明，而非内部实现细节，因此不会将私有或包级别的内部字段暴露在文档中。

• 内部实现并非对应简单字段：实际上LocalTime的内部存储结构并非直接对应second、nano这类独立字段。比如它源码中仅用一个private final long secondOfDay;变量来存储核心数据，纳秒等信息是通过计算推导出来的。如果在Javadoc中虚构这类“字段”，反而会误导开发者对类实现的理解。

• API设计的一致性要求：Java时间API整体遵循“通过方法访问状态”的设计风格，从LocalDate到LocalDateTime，所有核心时间类都只通过getter方法暴露状态，不直接对外展示内部字段。这种设计保证了API的一致性，让开发者无需关注每个类的内部存储细节，只用统一的方式获取所需数据。

简言之，Javadoc的作用是告诉你怎么用这个类，而不是展示它内部怎么实现。如果想了解内部字段细节，确实需要查看源码，但对于日常开发的使用需求来说，通过提供的getter方法就完全足够了。

内容的提问来源于stack exchange，提问作者xiaoqiang deng