README

oasis/dynamodb-odm 是一个 ODM（对象数据映射）库，用于方便地使用 AWS 强大的键值数据库：DynamoDb。

注意：本文档假设您对 DynamoDB 有一定的了解，以及 DynamoDB 与传统关系型数据库管理系统（如 MySQL）之间的区别。本文档中讨论的一些术语和概念是 DynamoDB 特有的，不会在本文档中解释。要学习 DynamoDB，请参阅官方开发指南

安装与配置

要获取 oasis/dynamodb-odm，您可以通过 composer 简单地 require 它

$ composer require oasis/dynamodb-odm

类加载

DynamoDb ODM 的自动加载由 composer 负责。您只需将 composer 自动加载文件包含到您的项目中即可

<?php

require_once "vendor/autoload.php";

获取 ItemManager

一旦您准备好了类加载，您就可以获取一个 ItemManager 实例。ItemManager 类是访问库提供的 ODM 功能的主要入口点。

<?php
use Oasis\Mlib\ODM\Dynamodb\ItemManager;

$awsConfig     = [
    "profile" => "oasis-minhao",
    "region"  => "ap-northeast-1"
];
$tablePrefix   = "odm-";
$cacheDir      = __DIR__ . "/ut/cache";
$isDev         = true;
$itemNamespace = 'Oasis\Mlib\ODM\Dynamodb\Ut'; // in practice, this usually looks like: My\Root\Namespace\Items
$itemSrcDir    = __DIR__ . "/ut"; // in practice, this usually points to src/Items directory

$im = new ItemManager(
    $awsConfig,
    $tablePrefix,
    $cacheDir,
    $isDev
);
$im->addNamespace(
    $itemNamespace,
    $itemSrcDir
);

下面将解释每个参数的含义

注意：Item 类定义了 ODM 管理的项目类型。一些典型的例子包括：User、Order、GameRoom 和 Card

设置命令行工具

DynamoDb ODM 随附了一些非常有用的命令行工具，它们在开发过程中非常有帮助。您可以从 Composer 二进制目录调用此命令

$ ./vendor/bin/oasis-dynamodb-odm

您需要将应用程序的 ItemManager 注册到控制台工具以使用内置命令。这是通过在调用目录下创建一个 odm-config.php 文件来完成的，内容如下

<?php
use Oasis\Mlib\ODM\Dynamodb\Console\ConsoleHelper;

// replace with file to your own project bootstrap
require_once 'bootstrap.php';

// replace with your own mechanism to retrieve the item manager
$itemManager = GetItemManager();

return new ConsoleHelper($itemManager);

详细的用法将在后面的部分中介绍

映射

ODM 库的基本功能是将对象模型（即类）映射到数据库结构。DynamoDb ODM 通过注释提供了方便的映射方法

<?php
use Oasis\Mlib\ODM\Dynamodb\Annotations\Field;
use Oasis\Mlib\ODM\Dynamodb\Annotations\Item;

/**
 * @Item(
 *     table="users",
 *     primaryIndex={"id"}
 * )
 */
class User
{
    /**
     * @var int
     * @Field(type="number")
     */
    protected $id;

    /**
     * @var string
     * @Field(type="string")
     */
    protected $name;
}

上面的类声明了一个简单的 User 模型，它将被映射到 DynamoDb 表 "users"（可能带有前缀）。下面的注释将进行解释

Item

您想使用 ODM 保存到数据库中的每个 PHP 对象都称为 "Item"。为了将对象描述为 Item，我们必须描述该对象的类。

使用 @Item 注释的类将由 ItemManager 管理。Item 接受以下属性

• table：对象的表名
• primaryIndex：主索引，可以是键的数组，或一个 @Index 注解对象
• globalSecondaryIndices：全局二级索引的数组；全局二级索引可以是键的数组，或一个 @Index 注解对象
• localSecondaryIndices：局部二级索引的数组；局部二级索引可以是键的数组，或一个 @Index 注解对象
• repository：仓库类名称；默认情况下，使用 \Oasis\Mlib\ODM\Dynamodb\ItemRepository
• 预测：是否仅预测此项目。《预测项目》不可更新（允许删除操作）。在读取（即获取/查询/扫描）预测项目时，仅从DynamoDB获取该项目的属性。

字段

将PHP类转换为Item后的下一步是将其实例属性映射到DynamoDb的属性中。

我们使用@Field注解来描述类属性，这些属性是DynamoDb属性。@Field注解支持以下属性

• type：属性类型，可以是以下之一
  • 字符串（默认）
  • 数字
  • 二进制
  • 布尔值
  • null
  • 列表
  • 映射
• name：DynamoDb属性名，如果它与属性名不同。默认值为null，表示属性键与属性名相同。

分区哈希键

分区哈希键是查询中用作哈希键的字段的扩展。存在这样的情况，您只想针对该字段的单个值（或非常少的值）进行查询。DynamoDB的性质将只会利用分配的读取容量的一小部分，从而限制您的系统性能。然而，通过使用该字段的分区哈希键，原始字段的每个值在分区哈希键字段中都将有一组映射值。通过并行查询这些分区值（请参阅多查询），在此用例中，您的查询性能应该会显著提高。

我们使用@PartitionedHashKey注解来描述分区哈希键字段。支持的属性包括

• baseField：原始字段名
• hashField：用作哈希源的值所在的字段，始终使用分布良好的字段作为哈希字段（例如，项目的唯一ID）
• size：分区大小，默认为16

索引

在声明不同的索引时，我们可以使用@Index注解来使文档块更易于阅读。一个@Index由两个键组成

• hash：哈希键名
• range：范围键名，如果没有此索引的范围键，则为空
• name：索引名，如果希望ODM为您自动生成一个，则为空。(注意：主索引不需要名称)

以下是在向User类添加全局二级索引时User类的声明

/**
 * @Item(
 *     table="users",
 *     primaryIndex={"id"},
 *     globalSecondaryIndices={
 *         @Index(hash="class", range="age", name="class-age-gsi")
 *     }
 * )
 */
class User
{
    // ...

    /**
     * @var string
     * @Field()
     */
    protected $class;

    /**
     * @var int
     * @Field(type="number")
     */
    protected $age;
}

检查和设置

一个字段可以声明为检查和设置字段，使用@Field注解的"cas"属性。

检查和设置字段是ODM用来确保不同工作员在相同时间不会对单个项目进行更新/插入超过一次的字段。

"cas"属性的值可以是以下之一

• disabled：这是默认值，具有"cas"禁用的字段在更新/插入项目时将不会被检查
• enabled：更新项目时将检查此字段的旧值。在插入项目时，此字段必须具有NULL值，或者不存在。
• timestamp：这是一种特殊的启用cas属性类型。每次更新/插入项目时，此字段的值都将自动设置为当前时间戳。

注意：仅在调用ItemManger#flush()时执行检查和设置验证。如果未满足检查和设置条件，则将抛出Oasis\Mlib\ODM\Dynamodb\Exceptions\DataConsistencyException异常。

与对象协作

ODM中的所有对象（项目）都得到管理。对象操作就像对象级事务一样得到管理。一旦对象被管理，无论是作为新对象持久化还是从数据库中检索，其管理状态都会存储在ItemManager中。对对象的任何更改都将记录在内存中。然后可以通过在ItemManager上调用ItemManager#flush()方法来提交对象更改。

可以通过调用ItemManager#clear()手动清除ItemManager。但是，尚未提交的任何更改都将丢失。

注意：非常重要的一点是理解，只有ItemManager#flush()才会对数据库执行写操作。其他任何方法，如ItemManager#persist($item)或ItemManager#remove($item)，都只是通知ItemManager在刷新时执行这些操作。不调用ItemManager#flush()将导致该请求期间的所有更改丢失。

持久化项目

可以通过将其传递给ItemManager#persist($item)方法来使项目持久化。通过在某个项目上应用持久化操作，该项目变为管理状态，这意味着其持久化现在由ItemManager管理。因此，当调用ItemManager#flush()时，此类项目的持久化状态将随后与数据库同步。

示例

<?php
/** @var ItemManger $im */
$user = new User();
$user->setName('Mr.Right');
$im->persist($user);
$im->flush();

移除项目

可以通过将其传递给ItemManager#remove($item)方法从持久化存储中移除项目。通过在某个项目上应用移除操作，该项目变为已移除，这意味着一旦调用ItemManager#flush()，其持久化状态将被删除。

示例

<?php
/** @var ItemManger $im */
/** @var User $user */
$im->remove($user);
$im->flush();

解除项目关联

可以通过在项目上调用ItemManager#detach($item)方法将其从ItemManager中解除关联，从而不再由ItemManager管理。在项目解除关联后，对解除关联的项目所做的任何更改（包括移除项目），都不会在项目解除关联后同步到数据库。

DynamoDb ODM将不会保留对解除关联项目的任何引用。

示例

<?php
/** @var ItemManger $im */
/** @var User $user */
$im->detach($user);
$user->setName('Mr.Left');
$im->flush(); // changes to $user will not be synchronized

与数据库同步

在ItemManager的flush()时，持久化项目的状态会与数据库同步。同步涉及将任何对持久化项目的更新写入数据库。当调用ItemManager#flush()时，ODM将检查所有被管理、新的和已删除的项目，并执行以下操作：

• 在数据库中创建新对象
• 更新数据库中已管理项目的更改属性
• 从数据库中删除已删除的项目

检索项目

DynamoDb ODM提供以下方法来检索持久化对象（按功能强大和灵活性递增），您应始终从适合您需求的最简单方法开始。

通过主索引

检索持久化对象的最基本方法是使用ItemManager#get($itemClass, $primayKeys)方法根据其主索引获取。以下是一个示例

<?php
/** @var ItemManager $im */
$user = $im->get(User::class, ["id" => 1]);

返回值是找到的项目实例或null，如果无法使用给定的标识符找到实例。

本质上，ItemManager#get()只是以下操作的快捷方式

/** @var ItemManager $im */
/** @var ItemRepository $userRepo */
$userRepo = $im->getRepository(User::class);
$user = $userRepo->get(["id" => 1]);

通过可查询索引上的简单条件

要基于简单条件查询一个或多个项目，请在存储库上使用ItemManager#query()和ItemManager#queryAndRun()方法，如下所示

/** @var ItemManager $im */
/** @var ItemRepository $userRepo */
$userRepo = $im->getRepository(User::class);
/** @var Users[] $users */
$users = $userRepo->query(
    "#class = :class AND #age >= :minAge",
    [
        ":class" => "A",
        ":minAge" => 25,
    ],
    "class-age-index"
);

注意：简单条件是仅使用一个索引的条件。如果使用的索引包含哈希键和范围键，则只有在哈希键也出现在条件中时才能使用范围键。此外，只能对哈希键执行相等测试操作。

通过分区哈希键的多查询

要基于PartitionedHashKey查询一个或多个项目，请在存储库上使用ItemManager#multiQueryAndRun()方法，如下所示

/** @var ItemManager $im */
/** @var ItemRepository $userRepo */
$userRepo = $im->getRepository(User::class);
/** @var Users[] $users */
$users = $userRepo->multiQueryAndRun(
    function ($item) {
        // each item returned can be accessed here in the callback
    },
    "classPartition", // PartitionedHashKey field name
    "A", // value expected in the base field (not the partition field)
    "#age >= :minAge", // only range conditions here
    [
        ":minAge" => 25,
    ],
    "class-partition-age-index" // index for PartitionedHashKey
);

通过不可查询索引的过滤器

要查询一个或多个没有关联索引的项目，请使用以下方法在存储库上调用ItemManager#scan()和ItemManager#scanAndRun()方法

/** @var ItemManager $im */
/** @var ItemRepository $userRepo */
$userRepo = $im->getRepository(User::class);
/** @var Users[] $users */
$users = $userRepo->scan(
    "#class = :class AND #age >= :minAge AND #name = :name",
    [
        ":class" => "A",
        ":minAge" => 25,
        ":name" => "John",
    ],
);

使用命令行工具

DynamoDb ODM与库一起提供了一个可执行工具。安装后，以下内置命令可以帮助您管理项目的数据库模式

创建

$ ./vendor/bin/oasis-dynamodb-odm odm:schema-tool:create

创建命令将遍历所有管理的项目并创建相应的表。所有主索引、LSI和GSI也将被创建。

注意：如果已存在具有相同名称和前缀的表，将抛出异常。在这种情况下不会创建任何表。

注意：如果您想跳过创建现有的表（即只创建不存在的表），可以使用“--skip-existing-table”选项

更新

$ ./vendor/bin/oasis-dynamodb-odm odm:schema-tool:update

更新命令实际上是创建命令的一个更强大（但速度也更慢）版本。它检查所有管理的项目，并在表不存在时创建表。此外，如果表已存在但定义了不同的GSI，更新命令将相应地更新GSI。

注意：由于DynamoDb的特性，在表已创建后无法更新主索引或LSI。在开发环境中，建议在需要时删除表并重新创建。

注意：如果您只想查看数据库模式的变化而不执行实际更新，可以在命令行中指定“--dry-run”选项。程序将仅提示可能的变化而不执行它们。

删除

$ ./vendor/bin/oasis-dynamodb-odm odm:schema-tool:drop

删除命令将删除所有与管理的项目相关的表。不要在生产环境中运行此命令！