Psr-16 通用缓存库规范

清疚 2022-05-29 10:40 487阅读 0赞

来源：https://nai8.me/article/detail.html?id=344

# PSR-16 #

这篇文档描述了一个简单可扩展的缓存接口或缓存驱动程序，最终实现可能有很多辅助类的对象，但是功能和界面必须统一。

缓存是我们提高项目性能的常用技法，也是众多框架中最常见的功能之一，每个框架也都推出了专属于自己且功能多样的缓存库，这使得我们在开发中不得不学习多个框架的缓存，而它们的很多功能我们并不需要。

其实PSR-6已经解决了这个问题，但是它采用了一种相当正式且冗长的方式。我们希望有一更简单且标准化的规范，这就是PSR-16。

# 定义 #

调用类库、实现类库、生存时间值和过期时间都是从PSR-6复制过来的，因为这些概念都是对的。

## 调用类库（Calling Library） ##

使用缓存服务的类库，这个类库调用缓存服务，调用的是此缓存接口规范的具体「实现类库」，调用者不需要知道任何「缓存服务」的具体实现。

## 实现类库（Implementing Library） ##

此类库是对「缓存接口规范」的具体实现，封装缓存服务，供「调用类库」使用。该实现类库必须提供一个实现Psr\\SimpleCache\\CacheInterface接口的类。必须支持最小的TTL功能，秒级别的精准度。

## 生存时间值（The Time To Live\[TTL\]） ##

缓存可以存活的时间，TTL通常被定义为整数或者一个DateInterval对象。

## 过期时间（Expiration） ##

过期时间点，一般为缓存存储的时间点加上 TTL 时间值。

在1:30:00存储300秒TTL的项目将在1:35:00到期。

「实现类库」可以在一个缓存过期之前将其设置为过期，但是一旦到达了过期时间，必须将其视为过期。如果「调用类库」在保存一个缓存项的时候未设置「过期时间」、或者设置了null作为过期时间（或者TTL设置为null），「实现类库」可以使用默认自行配置的一个时间。如果没有默认时间，「实现类库」必须把存储时间当做**永久性存储**，或者按照底层驱动能支持的最长时间作为保持时间。

如果过期时间提供复数或0TTL，则必须将缓存进行删除，因为它已经过期了。

## 键（Key） ##

长度大于1的字串，用作缓存项在缓存系统里的唯一标识符。键由字符A-Z，a-z，0-9，\_和.以任何顺序组成的UTF-8编码且长度最多为64个字符传。「实现类库」可以支持更多的编码或者更长的长度，不过**必须**支持至少以上指定的编码和长度。「实现类库」可自行实现对「键」的转义，但是**必须**保证能够无损的返回「键」字串。以下的字串作为系统保留: \{\}()/\\@:，一定不可作为「键」的命名支持。

## 缓存对象（Cache） ##

一个实现Psr\\SimpleCache\\CacheInterface接口的对象。

## 未命中（Cache Misses） ##

缓存未命中将返回空值并因此我们知道如果一个存储空值是不可能的。

# 数据 #

「实现类库」必须支持所有可序列化的PHP数据类型，包括：

*  字符串 - 任何大小的PHP兼容的字符串。
 *  整数 - PHP支持的低于64位的有符号整数值
 *  浮点数 - 所有的有符号浮点数
 *  布尔 - true和false.
 *  Null - null值（当缓存未命中时我们读取回来的也是null值）
 *  数组 - 各种形式的PHP数组（一维或多维）
 *  对象 - 所有的支持无损序列化和反序列化的对象，如：$o == unserialize(serialize($o))。对象可以使用PHP的serializable 接口，**\_\_sleep()**或者**\_\_wakeup()**魔术方法，或者在合适的情况下，使用其他类似的语言特性。

包括类型在内，所有存入「实现类库」的数据必须完全一致的取回才可以，如果存进缓存的是字符串5，取出来的却是整数值5的话，那是严重的错误。

「实现类库」可以使用PHP的「serialize()/unserialize()方法」作为底层实现，不过不强迫这样做。对于他们的兼容性，以能支持所有数据类型作为基准线。

实在无法「完整取出」存入的数据的话，实现类库**必须**把「未命中」标示作为返回，而不是损坏了的数据。

# 缓存接口（CacheInterface） #

「缓存接口」定义对缓存条目集合的最基本操作，这里包括基本的读取、写入和删除单个缓存。

另外「缓存接口」还支持一次删除多个缓存以及数据的批量写入和读取等，当你需要快速的完成缓存读写操作时，这些方法是非常有用的。

CacheInterface的实例对应于具有单个键名称缓存项的单个集合，相当于PSR-6中的“池”。不同的CacheInterface实例可以由同一个数据存储支持，但必须在逻辑上独立。(即可以实现相同存储类型的多个接口类，但是它们生成的对象都是彼此独立的。)

namespace Psr\SimpleCache;
    
    interface CacheInterface {
        /** * Fetches a value from the cache. * * @param string $key The unique key of this item in the cache. * @param mixed $default Default value to return if the key does not exist. * * @return mixed The value of the item from the cache, or $default in case of cache miss. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if the $key string is not a legal value. */
        public function get($key, $default = null);
    
        /** * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time. * * @param string $key The key of the item to store. * @param mixed $value The value of the item to store, must be serializable. * @param null|int|\DateInterval $ttl Optional. The TTL value of this item. If no value is sent and * the driver supports TTL then the library may set a default value * for it or let the driver take care of that. * * @return bool True on success and false on failure. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if the $key string is not a legal value. */
        public function set($key, $value, $ttl = null);
    
        /** * Delete an item from the cache by its unique key. * * @param string $key The unique cache key of the item to delete. * * @return bool True if the item was successfully removed. False if there was an error. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if the $key string is not a legal value. */
        public function delete($key);
    
        /** * Wipes clean the entire cache's keys. * * @return bool True on success and false on failure. */
        public function clear();
    
        /** * Obtains multiple cache items by their unique keys. * * @param iterable $keys A list of keys that can obtained in a single operation. * @param mixed $default Default value to return for keys that do not exist. * * @return iterable A list of key => value pairs. Cache keys that do not exist or are stale will have $default as value. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if $keys is neither an array nor a Traversable, * or if any of the $keys are not a legal value. */
        public function getMultiple($keys, $default = null);
    
        /** * Persists a set of key => value pairs in the cache, with an optional TTL. * * @param iterable $values A list of key => value pairs for a multiple-set operation. * @param null|int|\DateInterval $ttl Optional. The TTL value of this item. If no value is sent and * the driver supports TTL then the library may set a default value * for it or let the driver take care of that. * * @return bool True on success and false on failure. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if $values is neither an array nor a Traversable, * or if any of the $values are not a legal value. */
        public function setMultiple($values, $ttl = null);
    
        /** * Deletes multiple cache items in a single operation. * * @param iterable $keys A list of string-based keys to be deleted. * * @return bool True if the items were successfully removed. False if there was an error. * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if $keys is neither an array nor a Traversable, * or if any of the $keys are not a legal value. */
        public function deleteMultiple($keys);
    
        /** * Determines whether an item is present in the cache. * * NOTE: It is recommended that has() is only to be used for cache warming type purposes * and not to be used within your live applications operations for get/set, as this method * is subject to a race condition where your has() will return true and immediately after, * another script can remove it making the state of your app out of date. * * @param string $key The cache item key. * * @return bool * * @throws \Psr\SimpleCache\InvalidArgumentException * MUST be thrown if the $key string is not a legal value. */
        public function has($key);
    }

# 异常（CacheException） #

此异常用于缓存系统发生的所有严重错误

namespace Psr\SimpleCache;
    
    /** * Interface used for all types of exceptions thrown by the implementing library. */
    interface CacheException {
    }

# 传参错误异常（InvalidArgumentException） #

当一个错误或者非法的传参发生时，**必须**抛出此异常。

namespace Psr\SimpleCache;
    
    /** * Exception interface for invalid cache arguments. * * When an invalid argument is passed it must throw an exception which implements * this interface */
    interface InvalidArgumentException extends CacheException {
    }