/**
- 用户对象的基于内存的简单缓存服务。
-
特性与行为：
-
-
- 键：使用 {@link User#id()} 作为缓存键；值：{@link User}。
-
- 过期：每个条目在写入时记录过期时间点（expireAt）。读取时若发现已过期，将返回空结果但不会自动移除；
-
需要通过 {@link #evictExpired()} 主动淘汰。</li>
-
- 边界：条目仅在当前时间严格晚于 expireAt 时被视为过期（即等于 expireAt 时仍视为有效）。
-
- 并发：通过 {@link java.util.concurrent.locks.ReadWriteLock ReadWriteLock} 保证线程安全。
-
读操作（{@link #get(Long)}、{@link #size()}）持有读锁，允许并发读；写操作（{@link #put(User, java.time.Duration)}、
-
{@link #evictExpired()}、{@link #evictById(Long)}）持有写锁，互斥执行，确保与读操作的一致性。</li>
-
- 一致性：在读锁保护下读取与过期判断具备一致的时间视图；在写锁保护下的变更对后续读可见。
-
容量与清理：
{@link #size()} 返回的是当前存储的条目数量，可能包含已过期但尚未被淘汰的条目。
建议结合调度器周期性调用 {@link #evictExpired()} 回收过期条目。
使用示例：
{@code
UserCacheService cache = new UserCacheService();
// 写入：TTL 为 5 分钟
cache.put(new User(1L, "Alice", "alice@example.com"), Duration.ofMinutes(5));
// 读取：存在且未过期返回 Optional.of(user)，否则 Optional.empty()
Optional<UserCacheService.User> u = cache.get(1L);
// 主动淘汰过期条目（可周期性调用）
int removed = cache.evictExpired();
// 按 ID 逐出
cache.evictById(1L);
}
周期性淘汰示例（外部调度）：
{@code
ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
scheduler.scheduleAtFixedRate(cache::evictExpired, 1, 1, TimeUnit.MINUTES);
}
@see Optional
@see java.time.Duration
@see java.time.Instant
@see java.util.concurrent.locks.ReadWriteLock
@see java.util.concurrent.ScheduledExecutorService
*/
public class UserCacheService {
private final java.util.concurrent.ConcurrentMap<Long, CacheEntry> store = new java.util.concurrent.ConcurrentHashMap<>();
private final java.util.concurrent.locks.ReadWriteLock lock = new java.util.concurrent.locks.ReentrantReadWriteLock();
/**
- 根据用户 ID 读取缓存中的 {@link User}。
-
行为：
-
-
- 若不存在对应条目，返回 {@code Optional.empty()}。
-
- 若条目已过期，返回 {@code Optional.empty()}（不做删除）。
-
- 若存在且未过期，返回 {@code Optional.of(user)}。
-
并发：在读锁下执行，允许与其他读操作并发。
@param id 用户 ID，不能为空
@return 包含用户的 Optional，或空 Optional
@throws NullPointerException 当 {@code id} 为 {@code null} 时抛出
*/
public java.util.Optional get(Long id) {
java.util.Objects.requireNonNull(id, "id");
lock.readLock().lock();
try {
CacheEntry e = store.get(id);
if (e == null) return java.util.Optional.empty();
if (e.isExpired()) return java.util.Optional.empty();
return java.util.Optional.of(e.user);
} finally { lock.readLock().unlock(); }
}
/**
- 将用户写入缓存，并为该条目设置存活时间（TTL）。
-
语义：
-
-
- 过期时间计算为 {@code Instant.now().plus(ttl)}。
-
- 若相同 ID 的条目已存在，将被替换为新条目与新的过期时间。
-
- 在过期时间点本身（即 {@code now.equals(expireAt)}）视为仍未过期。
-
并发：在写锁下执行，与其他写操作互斥，并阻塞并发读以确保一致性。
@param user 用户对象，不能为空
@param ttl 生存时间，必须为正数（大于 0）
@throws NullPointerException 当 {@code user} 或 {@code ttl} 为 {@code null} 时抛出
@throws IllegalArgumentException 当 {@code ttl} 小于等于 0 时抛出
@see java.time.Duration#isNegative()
@see java.time.Duration#isZero()
*/
public void put(User user, java.time.Duration ttl) {
java.util.Objects.requireNonNull(user, "user");
java.util.Objects.requireNonNull(ttl, "ttl");
if (ttl.isNegative() || ttl.isZero()) {
throw new IllegalArgumentException("ttl must be positive");
}
lock.writeLock().lock();
try {
store.put(user.id(), new CacheEntry(user, java.time.Instant.now().plus(ttl)));
} finally { lock.writeLock().unlock(); }
}
/**
- 淘汰所有已过期的条目，并返回本次移除的数量。
-
语义与边界：
-
-
- 在一次遍历中使用同一时间点 {@link java.time.Instant#now()} 的快照作为判断基准。
-
- 仅当条目的 {@code expireAt} 严格早于该时间点时才会被移除（等于该时间点不会移除）。
-
并发：在写锁下执行，与读写操作互斥，保证移除期间的可见性与一致性。
@return 被移除的条目数
*/
public int evictExpired() {
int[] removed = new int[1];
lock.writeLock().lock();
try {
java.util.Iterator<java.util.Map.Entry<Long, CacheEntry>> it = store.entrySet().iterator();
java.time.Instant now = java.time.Instant.now();
while (it.hasNext()) {
java.util.Map.Entry<Long, CacheEntry> e = it.next();
if (e.getValue().expireAt.isBefore(now)) {
it.remove();
removed[0]++;
}
}
return removed[0];
} finally { lock.writeLock().unlock(); }
}
/**
- 按 ID 逐出（删除）缓存条目。若不存在则无操作。
-
并发：在写锁下执行。
- @param id 用户 ID，不能为空
- @throws NullPointerException 当 {@code id} 为 {@code null} 时抛出
*/
public void evictById(Long id) {
java.util.Objects.requireNonNull(id, "id");
lock.writeLock().lock();
try {
store.remove(id);
} finally { lock.writeLock().unlock(); }
}
/**
/**
- 缓存条目的内部表示，包含 {@link User} 与过期时间点。
-
过期判断：
-
-
- {@link #isExpired()} 使用 {@code Instant.now().isAfter(expireAt)} 判断是否过期。
-
- 因此仅当当前时间严格晚于 {@code expireAt} 时返回 {@code true}。
-
*/
static final class CacheEntry {
final User user;
final java.time.Instant expireAt;
/**
* 构造一个缓存条目。
*
* @param user 用户
* @param expireAt 过期时间点
*/
CacheEntry(User user, java.time.Instant expireAt) {
this.user = user;
this.expireAt = expireAt;
}
/**
* 判断条目是否已过期。
*
* <p>当且仅当 {@code Instant.now().isAfter(expireAt)} 时返回 {@code true}。
*
* @return 是否已过期
* @see java.time.Instant#isAfter(java.time.Instant)
*/
boolean isExpired() { return java.time.Instant.now().isAfter(expireAt); }
}
/**
- 简单的不可变用户模型，包含 ID、姓名与邮箱。
-
相等性与哈希：
-
-
- {@link #equals(Object)} 与 {@link #hashCode()} 仅基于 {@link #id()} 判断与计算。
-
- 这与缓存键一致：缓存以 {@link #id()} 作为键。
-
使用示例：
{@code
User u = new User(1L, "Alice", "alice@example.com");
Long id = u.id(); // 1L
String name = u.name(); // "Alice"
String email = u.email(); // "alice@example.com"
}
*/
public static final class User {
private final Long id;
private final String name;
private final String email;
/**
* 构造函数。
*
* @param id 用户 ID，不能为空
* @param name 用户姓名，不能为空
* @param email 用户邮箱，不能为空
* @throws NullPointerException 当任一参数为 {@code null} 时抛出
*/
public User(Long id, String name, String email) {
this.id = java.util.Objects.requireNonNull(id, "id");
this.name = java.util.Objects.requireNonNull(name, "name");
this.email = java.util.Objects.requireNonNull(email, "email");
}
/**
* 返回用户 ID。
*
* @return 用户 ID
*/
public Long id() { return id; }
/**
* 返回用户姓名。
*
* @return 用户姓名
*/
public String name() { return name; }
/**
* 返回用户邮箱。
*
* @return 用户邮箱
*/
public String email() { return email; }
/**
* 基于 {@link #id()} 的相等性判断。
*
* @param o 待比较对象
* @return 当且仅当对象为 {@link User} 且 ID 相等时返回 {@code true}
*/
@Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof User)) return false; User u=(User)o; return java.util.Objects.equals(id,u.id); }
/**
* 基于 {@link #id()} 的哈希值。
*
* @return 哈希值
*/
@Override public int hashCode() { return java.util.Objects.hash(id); }
}
}
