Java方法注释生成器

/**

• Retrieves a specific page of results for the given query, using a read-through cache.
• The method first attempts to return the page from the cache using the key pattern
• q:{hash}:p{page}:s{size}. On a cache miss, it loads the page from the database,
• stores it in the cache with the provided TTL, and returns it. On every access
• (hit or miss), the cache entry's TTL is refreshed.
• Caching details:
• • Key format: q:{hash}:p{page}:s{size}, where {hash} uniquely represents the query.
• • TTL behavior: refreshed on cache hit and after writing on miss.
• Constraints:
• • Page index is 1-based.
• • Size must be within [1, 100].
• @param query the query representing the data set to paginate; used to compute the cache key

•          and to load data on cache miss
  

• @param page the 1-based page number to retrieve; must be >= 1
• @param size the number of items per page; must be between 1 and 100 (inclusive)
• @param ttl the time-to-live to apply to the cached page; refreshed on each access
• @param cache the cache used to store and retrieve page results
• @return a Page containing the items for the requested page, the total item count,

•     the requested page and size, and a hasNext flag derived from total, page, and size
  

• @throws IllegalArgumentException if page < 1 or size is outside [1, 100]
• @throws DataAccessException if a database access error occurs while loading on cache miss

• Example:

• For page=2 and size=10, the method returns items 11–20 of the ordered result set defined by the query.

• Usage example:

• {@code
• Page page = paginateAndCache(userQuery, 2, 10, Duration.ofMinutes(5), cache);
• }

• Notes:

• • hasNext is true when page * size < total.
• • The {hash} part of the key must uniquely identify the logical query; collisions can lead to incorrect sharing of cached pages.

*/

/**

• 按指数退避（含随机抖动）的策略对可重试异常进行重试，并在失败率过高时结合熔断器短路调用。
• 每次尝试均注入/传播 traceId 并记录日志。若异常不满足重试条件或达到尝试上限，则按照约定抛出异常。
• 重试策略说明：
• • 延迟采用指数退避，并在每轮加入随机抖动以降低惊群效应
• • 使用熔断器监测失败率；当熔断器开启时，后续调用将被短路而不执行实际操作
• @param 操作成功时返回结果的类型
• @param action 待执行的操作供应者；每次重试都会重新调用该操作
• @param retryOn 异常重试判定器；当返回 true 且未超过最大尝试次数时按退避策略重试，否则立即传播异常
• @param maxAttempts 最大尝试次数（包含首次执行），必须 >= 1
• @param baseDelay 初始等待时长，用于计算每次重试的指数退避延迟
• @param scheduler 控制异步延时/定时的调度器，用于非阻塞地安排等待与再次尝试
• @return 操作成功执行的结果
• @throws InterruptedException 在等待或调度期间线程被中断时抛出
• @throws java.util.concurrent.TimeoutException 在等待或执行过程中触发超时策略时抛出
• @throws Throwable 当超过最大尝试次数时，抛出最后一次尝试产生的异常；或当 retryOn 返回 false 时立即传播该异常
• 使用示例：

• {@code
  

• // 场景：对网络请求的瞬时超时进行最多 3 次尝试（含首次），初始退避 200ms
• String body = executeWithRetry(

• () -> httpClient.get(url).execute(),                    // 具体网络调用
  

• ex -> ex instanceof java.net.SocketTimeoutException     // 可重试异常判定
  

•       || ex instanceof java.io.IOException,
  

• 3,                                                      // 最大尝试次数
  

• java.time.Duration.ofMillis(200),                       // 初始退避
  

• scheduler                                               // 由调用方提供的调度器
  

• );
• }
• 注意事项：
• • action 建议满足幂等性，或具备重放补偿措施，以避免重试导致的副作用累积
• • 熔断器开启时，调用可能在未执行 action 的情况下被短路；短路时的异常类型取决于熔断器实现
• • 退避为指数增长并加入随机抖动；baseDelay 过小可能导致退避不足，过大将增加总体延迟
• • scheduler 应为可复用的长期实例，避免频繁创建造成线程/资源开销；异步场景下请确保 traceId 上下文能够随调度正确传播 */