筋斗云接口编程 / 虚拟字段

虚拟字段

前面已经学习过怎样把一个数据库中的表作为对象暴露出去。
其中，表的字段就可直接映射为对象的属性。对于不在对象主表中定义的字段，统称为虚拟字段。

通过$vcolDefs来定义虚拟字段，最简单的一类虚拟字段是字段别名，比如

class AC1_Ordr extends AccessControl
{
    protected $vcolDefs = [
        [ "res" => ["t0.id orderId", "t0.dscr description"] ],
    ]
}

这样就为Ordr对象增加了orderId与description两个虚拟字段。
在get/query接口中，是可以用它们作为查询字段的，比如：

Ordr.query(cond="orderId>100 and description like '红色'")

在query接口中，虚拟字段与真实字段使用起来几乎没有区别。对外接口只有对象名，没有表名的概念，比如不允许在cond参数中指定”t0.orderId>100”。

关联字段

[任务]

在订单的query/get接口中，只有userId字段，为了方便显示用户姓名和手机号，需要增加虚拟字段userName, userPhone字段。
另外，还需要增加虚拟字段“订单创建时间” - createTm，实现时这个字段需要从OrderLog表中获取。

设计文档中定义接口如下：

Ordr.query() -> tbl(id, dscr, ..., userName?, userPhone?, createTm?)

其中userName/userPhone字段分别关联到User.name和User.phone字段的，而createTm字段是关联到OrderLog.tm字段的。

习惯上，我们在query或get接口的字段列表中加”…”表示参考数据表定义中的字段，而”…”之后描述的就是虚拟字段。
虚拟字段上的后缀”?”表示该字段默认不返回，仅当在res参数中指定才会返回，如：

Ordr.query(res="*,userName")

一般虚拟字段都建议默认不返回，而是按需来取，以减少关联表或计算带来的开销。

在cond参数中可以直接使用虚拟字段，不管它是否在res参数中指定，如

Ordr.query(cond="userName LIKE '%john%'", res="id,dscr")

实现时，通过设置属性$vcolDefs实现这些关联字段：

class AC1_Ordr extends AccessControl
{
    protected $vcolDefs = [
        [
            "res" => ["u.name AS userName", "u.phone AS userPhone"],
            "join" => "INNER JOIN User u ON u.id=t0.userId",
            // "default" => false, // 与接口原型中字段是否可缺省(是否用"?"标记)对应
        ],
        [
            "res" => ["log_cr.tm AS createTm"],
            "join" => "LEFT JOIN OrderLog log_cr ON log_cr.action='CR' AND log_cr.orderId=t0.id",
        ]
    ]
}

• 以上很多表或字段指定了别名，比如表”User u”，字段”u.name AS userName”。在指定别名时，关键字”AS”可以省略。
• 表的别名不是必须的，除非有多个同名的表被引用。
• 如果指定”default”选项为true, 则调用Ordr.query()时如果未指定”res”参数，会默认会带上该字段。

关联字段依赖

假设设计有“订单评价”对象，它与“订单”相关联：

@Rating: id, orderId, content

一个订单可有多个评价，表间的关系为：

订单评价Rating(orderId) n<->1 订单Ordr
订单Ordr(userId) n<->1 用户User

现在要为Rating表增加关联字段订单描述 “Ordr.dscr AS orderDscr”, 以及客户姓名 “User.name AS userName”, 设计接口为：

Rating.query() -> tbl(id, orderId, content, ..., orderDscr?, userName?)

注意：userName字段不直接与Rating表关联，而是通过Ordr表桥接过去。

如果这样定义:

class AC1_Rating extends AccessControl
{
    protected $vcolDefs = [
        [
            "res" => ["o.dscr AS orderDscr"],
            "join" => "INNER JOIN Ordr o ON o.id=t0.orderId",
        ],
        [
            "res" => ["u.name AS userName"],
            "join" => "INNER JOIN User u ON o.userId=u.id",
        ],
    ];
}

这样查询是没有问题的:

Rating.query(res="id,orderDscr,userName")

但如果这样查询(只查User表上)

Rating.query(res="id,userName")

这时将出错, 因为框架只知道userName字段需要联接User表, 而不知道必须先联接Ordr表.

一种解决方案是将两个表写在一起:

class AC1_Rating extends AccessControl
{
    protected $vcolDefs = [
        [
            "res" => ["o.dscr AS orderDscr", "u.name AS userName"],
            "join" => "INNER JOIN Ordr o ON o.id=t0.orderId INNER JOIN User u ON o.userId=u.id",
        ]
    ];
}

其缺点是, 即使是只查询Ordr表的orderDscr字段, 也要联接User表, 而这是不必要的.

正确做法是，在vcolDefs中可以使用require选项指定依赖字段：

class AC1_Rating extends AccessControl
{
    protected $vcolDefs = [
        [
            "res" => ["o.dscr AS orderDscr"],
            "join" => "INNER JOIN Ordr o ON o.id=t0.orderId",
        ],
        [
            "res" => ["u.name AS userName"],
            "join" => "INNER JOIN User u ON o.userId=u.id",
            "require" => "userId" // *** 定义依赖，如果要用到res中的字段如userName，则自动添加orderDscr字段引入的表关联。
        ]
    ];
}