StartMVC开发手册

可以快速上手的开发文档

手册目录

数据查询

数据查询Fetch

可使用的方法有:get(),first(),value(),column(),find(),chunk()

查询多条数据get() 或many()

get($type), 如果$type为true时,不执行查询,直接返回构建的sql语句

// 获取多条记录
Db::table('test')->get();
// 生成SQL: "SELECT * FROM test"

// 获取指定字段的多条记录
Db::select('title')->table('pages')->where('id', 17)->get();
// 生成SQL: "SELECT title FROM pages WHERE id='17'"

// 获取指定字段的多条记录
Db::select('username')->table('users')->where('status', 1)->get();
// 生成SQL: "SELECT username FROM users WHERE status='1'"

获取单条数据 First()或 one() 别名

成功返回一维数据,失败返回null

$user = Db::table('users')->where('status', 1)->first();
// 结果:单个用户对象或数组

获取单一字段 Value

成功返回字段值对应的数值,失败返回null, 这个方法可以从一条数据中获取到单一字段的值

// 获取单个字段的值
$username = Db::table('users')->where('id', 1)->value('username');
// 结果:字符串 "admin"

按字段提取列数据column

获取单列数据:

// 获取所有用户名
$usernames = Db::table('users')->column('username');
// 结果: ['admin', 'user1', 'user2', ...]

构建键值对:

// 获取用户ID到邮箱的映射
$emails = Db::table('users')->column('email', 'id');
// 结果: [1 => 'admin@example.com', 2 => 'user1@example.com', ...]

用于选择框:

// 获取分类下拉框选项
$categories = Db::table('categories')->column('name', 'id');
// 在视图中使用
foreach ($categories as $id => $name) {
 echo "{$name}";
}

快速按主键查询find

方法有find(),findMany()

find($id) 通过主键查找单条记录,返回记录数组或 null

find($id, $key, true) 查找记录,找不到抛异常 ,返回记录数组

findMany($ids,$key) 通过主键数组查找多条记录 ,返回记录数组

findOrFail($id,$key) *已过时,使用 find($id, 'id', true)*,返回记录数组

基本用法

// 通过主键查找单条记录(默认找不到返回 null)
$user = $db->table('users')->find(1);

// 找不到会抛出异常(新方式)
try {
 $user = $db->table('users')->find(999, 'id', true); // 第三个参数控制是否抛异常
} catch (Exception $e) {
 echo "用户不存在";
}

// 兼容旧方式(已标记为过时)
try {
 $user = $db->table('users')->findOrFail(999);
} catch (Exception $e) {
 echo "用户不存在";
}

// 批量查找多条记录
$users = $db->table('users')->findMany([1, 2, 3, 4, 5]);

// 使用自定义主键字段
$user = $db->table('users')->find('admin@example.com', 'email');

// 自定义主键 + 抛异常
$user = $db->table('users')->find('admin@example.com', 'email', true);

与传统方式对比

// 传统方式
$user = $db->table('users')->where('id', 1)->first();
$users = $db->table('users')->in('id', [1,2,3])->get();

// 使用 find 方法(更简洁)
$user = $db->table('users')->find(1);
$users = $db->table('users')->findMany([1,2,3]);

限制条数与偏移limit() / offset()

limit() 只接受行数一个参数:->limit(10) 生成 LIMIT 10,取前 10 条。要跳过前面的记录,链式加 offset():->limit(10)->offset(20) 生成 LIMIT 10 OFFSET 20。

// 取前 10 条
$articles = Db::table('articles')->limit(10)->get();

// 跳过前 20 条,再取 10 条
$articles = Db::table('articles')->limit(10)->offset(20)->get();

// 分页用 page($page, $perPage),页码从 1 开始
$articles = Db::table('articles')->page(3, 10)->get();

分页场景直接写 page($page, $perPage) 更省事,它内部就是 limit($perPage) 加 offset(($page - 1) * $perPage)。

limit() 不接受第二个参数。旧写法 limit($a, $b) 会直接抛出 InvalidArgumentException,不会静默降级。

还有两点容易踩:limit(0) 是「取 0 条」,返回空集,不是「不限制」;只写 offset() 而不写 limit() 时,框架会自动补上 LIMIT 18446744073709551615,因为 MySQL 不支持单独的 OFFSET。

分块遍历chunk()

chunk($count, $callback, $column = null),用于大数据量遍历:每批取 $count 行交给回调处理,再按推进列(默认主键 id)从上一批的最大值继续往后取,直到取完。每批只驻留 $count 行数据,内存占用与总行数无关。成功返回累计处理的行数。

参数说明:

  • $count 每批行数,必须大于 0
  • $callback 回调函数,签名为 function (array $rows),返回 false 可提前终止遍历
  • $column 推进列,默认 id,需为唯一且可排序的列(通常是自增主键)

基本用法:

// 分批处理 5 万条订单,每批 1000 行
$total = Db::table('orders')->where('status', 1)->chunk(1000, function ($rows) {
 foreach ($rows as $row) {
 // 处理每一行数据……
 }
});

echo "共处理 {$total} 行";

回调返回 false 提前终止:

Db::table('logs')->chunk(500, function ($rows) {
 foreach ($rows as $row) {
 if ($row['level'] === 'error') {
 return false; // 不再取下一批,遍历到此结束
 }
 }
});

自定义推进列(表没有 id 列时):

Db::table('user_stats')->chunk(200, function ($rows) {
 // ...
}, 'user_id');

边遍历边写库:

// 按主键推进,遍历过程中更新或删除已处理的行不会漏行、不会重复
Db::table('users')->where('synced', 0)->chunk(1000, function ($rows) {
 foreach ($rows as $row) {
 Db::table('users')->where('id', $row['id'])->update(['synced' => 1]);
 }
});

在模型上使用(自动带上软删除范围):

$userModel = $this->model('User');

$userModel->where('status', 1)->chunk(1000, function ($rows) {
 // 已软删除的记录不会被遍历到
});

与事务配合,任意一批出错即整体回滚:

Db::transaction(function () {
 Db::table('orders')->where('status', 1)->chunk(1000, function ($rows) {
 foreach ($rows as $row) {
 // 任意一步抛异常,整个事务回滚
 }
 });
});

事务的完整用法(嵌套事务、inTransaction()、手动模式等)见 事务操作及维护。

注意事项:

  1. 不要用 limit/offset 循环翻页来遍历全表:遍历过程中一旦有行被删除或插入,偏移量就会错位,导致已处理的行被跳过。chunk() 按推进列取值(WHERE id > 上一批最大值)推进,不受数据变动影响。
  2. 推进列必须唯一且可排序,默认主键 id;列名写错、或结果集里取不到该列时都会直接抛出异常,不会陷入死循环。
  3. 每批的 order / limit / offset 由 chunk() 内部接管(按推进列 ASC + LIMIT $count),调用方不需要也不应再设置。
  4. chunk() 是「分批查询」,遍历过程中可以安全地写库或开启事务;而游标(unbuffered 流式读取)在同一连接上边读边写会报错,边读边写的场景请用 chunk()。
  5. chunk() 自身不包事务。需要「整批失败整体回滚」时把它放进 Db::transaction(function () { ... }) 里;但事务会持有锁,超大数据量建议每批单独提交。

和分页的关系

chunk() 和分页解决的不是同一个问题,但两者的推进方式同源:chunk() 内部用的 WHERE 推进列 > 上一批最大值 ORDER BY 推进列 ASC LIMIT $count,把「页码」换成「上一页最后一行的主键值」,就是游标分页(keyset pagination)。

按需求选:

  • 要页码、要总数、能跳页(后台列表页)→ Db::table('t')->page($page, $perPage) 取数据,或 Model::paginate() 一次拿到数据与 total / total_pages / current_page / has_more,再用 Pagination 渲染页码。
  • 只要「下一页」、翻得很深(无限滚动、导出)→ 游标分页,前端传上一页最后一条的主键(如 ?last_id=xxx),不要传页码。代价是拿不到总数、不能跳页。
  • 要遍历全表做处理(刷数据、导报表)→ chunk(),它没有「页」的概念,只有「批」。

为什么深翻页别用 OFFSET:LIMIT 10 OFFSET 19000 要先扫描并丢弃前 19000 行,读取行数随页码线性增长;游标写法恒定只读 10 行。2 万行实测:OFFSET 19000 读取 19010 行,游标读取 10 行。

分页的完整用法见 分页类,模型层的 paginate() 见 模型。

获取查询次数queryCount

返回查询的数据条数.

// 执行一系列查询操作
$db = Db::table('users')->where('status', 1)->get();
$articles = Db::table('articles')->limit(10)->get();
$category = Db::table('categories')->where('id', 5)->first();

// 获取已执行的查询总数
$count = Db::queryCount();
echo "执行的查询总数: " . $count; // 输出: 执行的查询总数: 3

影响行数numRows()

返回数据影响条数.

// 查询示例
$users = Db::table('users')->where('status', 1)->get();
$affectedRows = Db::numRows();
echo "查询影响的行数: " . $affectedRows; // 例如: 查询影响的行数: 5

// 更新示例
Db::table('articles')->where('category_id', 3)->update(['status' => 0]);
$updatedRows = Db::numRows();
echo "更新影响的行数: " . $updatedRows; // 例如: 更新影响的行数: 8

// 删除示例
Db::table('comments')->where('post_id', 10)->delete();
$deletedRows = Db::numRows();
echo "删除影响的行数: " . $deletedRows; // 例如: 删除影响的行数: 12

最新插入的id号insertId()

插入后读取最后插入的主键值。推荐直接用 insertGetId() 拿主键;insertId() 记录的是「最近一次插入」的状态,之后的任何查询都可能覆盖它。

// 推荐:插入的同时拿到主键
$newArticleId = Db::table('articles')->insertGetId([
 'title' => '新文章标题',
 'content' => '文章内容',
 'created_at' => date('Y-m-d H:i:s')
]);
echo "新插入文章的ID: " . $newArticleId; // 例如: 25

// 也可以插入后立刻读
Db::table('articles')->insert($data);
$newArticleId = Db::insertId();

插入类型、返回值语义与批量插入的注意事项,见 插入数据。

链式构建的注意事项

Db::table() 返回的是共享的查询构建器,不是每次新建的对象。查询一执行完,构建状态(where、limit、order、绑定值等)就会自动清空,只保留结果状态(insertId()、numRows()、getQuery())。由此有三条约束。

1. 不要跨查询复用同一个构建器

$q = Db::table('tools')->where('status', 1); // 尚未执行
$a = $q->where('cat_id', 1)->get(); // 执行完,构建状态已被清空
$b = $q->where('cat_id', 2)->get(); // ⚠ 不是「status 条件丢了」,而是整条链作废
 // 会生成 SELECT * FROM ...,直接报错

// 正确做法:需要复用条件就重建两次查询
$a = Db::table('tools')->where('status', 1)->where('cat_id', 1)->get();
$b = Db::table('tools')->where('status', 1)->where('cat_id', 2)->get();

2. 不要留下没有执行的链

只写了 table()/where() 却漏掉执行器(get()、first()、count()、update()、delete() 等),这条链会在下一次 table() 时被直接丢弃,不会报错。它不会再污染下一次查询,但也不会替你执行:

Db::table('tools')->where('id', 999); // 漏了执行器
$rows = Db::table('logs')->get(); // 正常查 logs,上一条链被丢弃(不会带上 id=999)

// 想让这条链执行,就补上执行器
Db::table('tools')->where('id', 999)->get();

3. 嵌套子查询是禁区

同一条表达式里调用两次 Db::table(),内层求值会清掉外层的表名,外层查询直接报错。需要子查询时,先把内层结果算出来:

// ⚠ 不要这样写
Db::table('tools')->where('id', Db::table('logs')->count())->get();

// 正确做法:先取内层结果
$n = Db::table('logs')->count();
Db::table('tools')->where('id', $n)->get();

字段和条件可以写在 table() 之前(如 Db::select('title')->table('pages')),但这类链必须紧跟 table() 并执行,不要留成「只有 where、没有表名」的悬空条件——它无法与下一条链区分,仍会串过去。

如果完全没指定表名就执行(例如 Db::where('id', 1)->get()),会直接抛 LogicException 并提示「未指定查询表名」,不会等到 MySQL 报 1064。

只想取 SQL 不执行:用 getSql(),它返回一个快照并立即清空当前构建状态,因此不会影响后续查询。写法是「先 getSql(),再链执行器」——getSql() 必须在执行器之前,因为「执不执行」要在执行前决定。

// 只出 SQL,不写库
$sql = Db::table('articles')->getSql()->insert($data);
$sql = Db::table('articles')->getSql()->insert($data, 'REPLACE'); // 指定插入类型
$sql = Db::table('articles')->getSql()->where('id', 1)->update(['title' => 'x']);

返回值是快照对象,不是字符串:getSql() 返回 SqlSnapshot(DbCore 的子类),必须再链一个执行器才拿到 SQL 字符串。可用的是全部「会产出 SQL」的执行器:

  • 查询:get() first() value() column(),以及 find() many() one() 等包装方法
  • 聚合:count() max() min() sum() avg()
  • 写入:insert() insertGetId() update() delete() invert() inc() dec() touch()
  • 表维护:truncate() drop() repair() optimize() analyze() check() checksum()

只写 getSql() 就 echo 或拼字符串不会报致命错误,而是输出一段以 -- 开头的提示文本(SQL 注释形式),提醒还没链执行器。

旧写法已移除:get(true)、first(true)、update($data, true)、delete(true) 这类「第二个参数传 true 只返回 SQL」的写法已删除,调用会抛 InvalidArgumentException 并提示改用 getSql()。之所以要主动抛异常:PHP 对用户函数的多余实参是静默忽略的,只删参数不拦的话,update($data, true) 会从「不执行」变成「真的写库」。

取 SQL 不写日志:getSql() 链不产生执行日志,Db::lastQuery() 取不到它——后者只记录真正执行过的语句。日志受配置 database.log_sql(0 关闭 / 1 只记写操作 / 2 全部记录,默认 2)与 log_sql_max(默认 1000 条,超出丢弃最旧)控制。

WHERE 条件与 OR 分组

多个 where() / orWhere() 之间是纯字符串拼接(用 AND / OR 连接),框架不会自动加括号。SQL 里 AND 的优先级高于 OR,所以只要一段条件里含 OR,它后面的 AND 就会被吃掉。

// ⚠ 错误:以为条件是「三个 LIKE 命中之一 且 status=1」
Db::table('users')
 ->where('name LIKE ? OR url LIKE ? OR email LIKE ?', [$kw, $kw, $kw])
 ->where('status', 1)
 ->getSql()->get();
// 生成: WHERE name LIKE '%a%' OR url LIKE '%a%' OR email LIKE '%a%' AND status = 1
// 实际语义: name LIKE .. OR url LIKE .. OR (email LIKE .. AND status = 1)
// → status=0 的记录也会被带出来

// ✅ 正确:OR 段自己加括号
Db::table('users')
 ->where('(name LIKE ? OR url LIKE ? OR email LIKE ?)', [$kw, $kw, $kw])
 ->where('status', 1)
 ->getSql()->get();
// 生成: WHERE (name LIKE '%a%' OR url LIKE '%a%' OR email LIKE '%a%') AND status = 1

三条可用的分组写法:

  1. 模板里手写括号:where('(a = ? OR b = ?)', [$x, $y]),最直白,适用于任意复杂条件。
  2. | / & 特殊字段语法:where('name|url', $kw) 生成 (name = ? OR url = ?),where('id&status', 1) 生成 (id = ? AND status = ?),框架自动加括号;但只支持等值匹配,不能配 LIKE。
  3. grouped() 闭包:
Db::table('users')
 ->grouped(function ($q) use ($kw) {
 $q->where('name', 'like', $kw)
 ->orWhere('url', 'like', $kw);
 })
 ->where('status', 1)
 ->get();
// 生成: WHERE (name LIKE '%a%' OR url LIKE '%a%') AND status = 1

为什么框架不默认加括号:where('id=? AND status=?', [1, 1]) 这类模板会被整体包成 (id=? AND status=?),所有 getSql() 输出与 SQL 日志文本都会变;而且确实有人靠 SQL 优先级写 a OR b AND c。需要分组就显式写出来——这与 Laravel、ThinkPHP 的行为一致。

三条容易踩的边界:

  • whereRaw('a = 1 OR b = 2') 同样不分组,后面再接 where() 一样会被 OR 吃掉,需要时自己包括号。
  • grouped() 的闭包里必须至少加一个条件。闭包内一个条件都没加时(例如可选筛选参数全为空),当前实现仍会补上右括号,生成 WHERE ) AND ... 的语法错误 SQL;可选条件请在闭包外先判断。
  • 数组条件的第 4 个元素(如 where([['a', '=', $x, 'OR'], ['b', '=', $y, 'OR']]))目前不生效,片段之间一律按外层逻辑连接(默认 AND),且不会报错。要 OR 请用 grouped() 或手写括号。