石头鱼的技术札记

MUST#

必须遵守。

含义：

• 属于架构边界规则
• 违反后会直接导致依赖方向失控、职责混乱或维护成本上升
• Code Review 与重构评审中应视为硬性约束

典型场景：

• pages 不得直接依赖 services/api
• 外部不得绕过 Feature 公开入口访问内部实现
• Layout 不得依赖具体 Feature

SHOULD#

强烈建议遵守。

含义：

• 属于高价值实践
• 一般情况下应执行
• 若因历史包袱、阶段性限制或技术约束无法完全满足，应在变更说明中明确原因

典型场景：

• 页面级复杂状态优先下沉到 Feature composables
• 页面主体优先下沉到 features/*/ui/pages/*
• 共享组件命名与分层语义保持一致

MAY#

可选实践。

含义：

• 在不破坏分层边界的前提下可按需要采用
• 不作为强制审查项

典型场景：

• 某些中性组件是否进入 components/shared
• 是否为 Feature 局部区块继续细拆更小粒度组件

使用原则#

• 涉及分层、依赖方向、公开接口、数据访问边界的规则，原则上应定义为 MUST。
• 涉及组织方式优化、工程一致性提升的规则，原则上定义为 SHOULD。
• 涉及实现风格偏好但不破坏架构边界的内容，可定义为 MAY。

职责#

• 创建应用实例
• 调用统一安装方法
• 执行挂载

约束#

• 不直接编写长串插件安装逻辑
• 不编写业务初始化逻辑
• 不编写权限逻辑
• 不编写布局逻辑

推荐写法#

1
import { createApp } from 'vue'
2
import App from './App.vue'
3
import { installApp } from './app/bootstrap/installApp'
4

5
const app = createApp(App)
6
installApp(app)
7
app.mount('#app')

职责#

• 装配根级 Providers
• 装配根级 Shell

约束#

• 不直接引入具体业务 Feature
• 不直接编写页面逻辑
• 不直接请求业务数据

推荐写法#

1
<template>
2
  <AppProviders>
3
    <AppShell />
4
  </AppProviders>
5
</template>
6

7
<script setup lang="ts">
8
import AppProviders from '@/app/providers/AppProviders.vue'
9
import AppShell from '@/app/shell/AppShell.vue'
10
</script>

职责#

• 集中安装插件、指令、错误处理
• 作为 main.ts 的负载转移层

示例#

1
import type { App } from 'vue'
2
import { router } from '@/router'
3
import { installPlugins } from './installPlugins'
4
import { installDirectives } from './installDirectives'
5

6
export function installApp(app: App) {
7
  app.use(router)
8
  installPlugins(app)
9
  installDirectives(app)
10
}

职责#

• 组织全局 Provider 容器
• 收纳 Toast、Dialog、主题、Query 等根级容器

职责#

• 组织应用根壳
• 承接根级 RouterView、LayoutHost、全局边界容器

Router 的职责#

• 定义路由表
• 定义守卫
• 通过 meta 提供页面装配信息

Router 的强约束#

• 路由组件必须指向 src/pages/*Page.vue
• 路由不得直接指向 features/*/ui/pages/*

推荐示例#

1
{
2
  path: '/workspace/tasks',
3
  component: () => import('@/pages/WorkspaceTasksPage.vue'),
4
  meta: { layout: 'dashboard', requiresAuth: true },
5
}

原则#

• 未登录跳转
• 无权限跳转
• 路由级权限判断

应在 router/guards/* 中处理，而不应下沉到 Layout 或具体页面中。

理由#

• Router Guard 更接近路由访问入口
• Layout 的职责应保持为页面壳，而非访问控制
• 页面层不应承担系统级访问决策

Layout 的定位#

Layout 是页面外壳，用于控制：

• Header
• Sidebar
• Breadcrumb
• 内容区容器
• 页面整体壳结构

Layout 的禁止事项#

• 不得直接导入 Feature
• 不得请求 Feature 数据
• 不得承载业务编排逻辑

推荐结构#

• LayoutHost.vue：读取 meta 并选择具体 Layout
• DefaultLayout.vue：通用布局
• EmptyLayout.vue：登录页、空白页
• DashboardLayout.vue：带导航和侧栏的后台布局
• layouts/parts/*：布局内部组成块

示例#

1
<template>
2
  <component :is="layoutComponent">
3
    <router-view />
4
  </component>
5
</template>
6

7
<script setup lang="ts">
8
import { computed } from 'vue'
9
import { useRoute } from 'vue-router'
10
import DefaultLayout from './DefaultLayout.vue'
11
import EmptyLayout from './EmptyLayout.vue'
12
import DashboardLayout from './DashboardLayout.vue'
13

14
const route = useRoute()
15

16
const layoutMap = {
17
  default: DefaultLayout,
18
  empty: EmptyLayout,
19
  dashboard: DashboardLayout,
20
}
21

22
const layoutComponent = computed(() => {
23
  const key = (route.meta.layout as keyof typeof layoutMap) || 'default'
24
  return layoutMap[key] || DefaultLayout
25
})
26
</script>

单 Feature 页面#

1
<template>
2
  <WorkspaceTasksPageView />
3
</template>
4

5
<script setup lang="ts">
6
import { WorkspaceTasksPageView } from '@/features/workspace'
7
</script>

带路由适配的页面#

1
<template>
2
  <ReviewDetailPageView :review-id="reviewId" />
3
</template>
4

5
<script setup lang="ts">
6
import { useRoute } from 'vue-router'
7
import { ReviewDetailPageView } from '@/features/review'
8

9
const route = useRoute()
10
const reviewId = String(route.params.reviewId)
11
</script>

Pages 允许承担的职责（MUST）#

• 作为 Router 的直接页面入口
• 读取 route.params 与 route.query
• 进行最小限度的参数适配与类型归一
• 选择并组合一个或多个 Feature 暴露出的 page view
• 向 Feature page view 透传路由级参数

Pages 不得承担的职责（MUST）#

• 不直接调用 services/api
• 不直接编写查询、写入逻辑
• 不承担复杂状态编排
• 不进行 DTO 到领域模型的转换
• 不处理页面核心业务规则

Feature Page View 的职责（MUST）#

features/*/ui/pages/* 作为页面主体视图，负责：

• 承载页面主要内容结构
• 组织本 Feature 的 partials 与 components
• 调用本 Feature 的页面级 composable
• 处理页面级业务展示逻辑

推荐边界理解（SHOULD）#

可将两者关系理解为：

• pages/*Page.vue = 路由适配层
• features/*/ui/pages/* = 页面主体层

推荐示例#

1
<template>
2
  <ReviewDetailPageView :review-id="reviewId" />
3
</template>
4

5
<script setup lang="ts">
6
import { useRoute } from 'vue-router'
7
import { ReviewDetailPageView } from '@/features/review'
8

9
const route = useRoute()
10
const reviewId = String(route.params.reviewId)
11
</script>

在该模式下，路由页仅完成参数适配，具体页面主体由 Feature 负责。

A. 单一业务域#

适用于规模中等、边界清晰、无需再拆分子域的 Feature。

1
features/<domain>/
2
  index.ts
3
  model/
4
  queries/
5
  mutations/
6
  composables/
7
  ui/

B. 大型业务域（带子域）#

适用于一级域下包含多个稳定语义模块的场景。

1
features/<domain>/
2
  <subdomain-a>/
3
  <subdomain-b>/
4
  <subdomain-c>/
5
  shared/
6
  index.ts
7
  model/

其中：

• 子域承载各自的实现
• shared/ 仅承载兄弟子域之间复用的内容
• index.ts 与 model/ 仍作为一级域的对外公开边界

子域结构规则#

子域不强制必须同时具备 model / queries / mutations / composables / ui 五类子目录。

应根据复杂度采用渐进式组织方式。

1
<subdomain>/
2
  model.ts
3
  queries.ts
4
  mutations.ts

1
<subdomain>/
2
  model.ts
3
  queries.ts
4
  mutations.ts
5
  composables/
6
  ui/

1
<subdomain>/
2
  model/
3
  queries/
4
  mutations/
5
  composables/
6
  ui/

子域 Shared 规则#

默认不设”子域自己的 shared/”。

原因如下：

• 子域内部共享通常尚不足以形成稳定的模块边界
• 过早引入多层 shared 容易导致结构膨胀
• 会削弱一级域 shared/ 的收敛作用

仅当某个子域本身已经足够复杂，且其内部再次形成明确子模块边界时，才允许在该子域内继续分模块并引入更细粒度共享目录。

一级域 shared/ 的使用边界#

一级域下的 shared/ 仅用于承载”跨子域复用”的内容。

允许进入一级域 shared/ 的内容包括：

• 跨子域复用的类型
• 跨子域复用的表单片段
• 跨子域复用的弹窗
• 跨子域复用的常量
• 跨子域复用的映射工具

禁止将以下内容放入一级域 shared/：

• 仅被单个子域使用的实现
• 尚未形成稳定复用关系的临时代码
• 本应留在子域内部的业务实现细节

一级域与子域的组织原则#

• 一级域负责聚合边界与公开接口。
• 子域负责自己的实现细节。
• 只有跨子域复用的内容才进入一级域 shared/。
• 小子域优先采用扁平文件。
• 复杂后再升级为完整分层目录。

职责#

• Feature 对外统一公开入口
• 白名单式导出允许外部使用的能力
• 当 Feature 为一级域时，负责聚合其子域对外能力

强约束#

外部模块只应从该入口使用 Feature 能力。

推荐导出内容#

• 页面级 page view
• 必要的编排 composable
• 少量需要跨页面复用的 UI 能力
• 一级域场景下，对外聚合后的子域能力

职责#

• 定义领域模型
• 定义 query keys
• 定义领域常量
• 提供稳定对外类型出口
• 在一级域场景下，承载该域统一对外的模型契约

说明#

当 Feature 为大型一级域时：

• 一级域下的 model/ 负责对外稳定模型边界
• 子域内部可以保留各自局部模型文件或目录
• 只有需要对一级域外部稳定暴露的模型契约，才应收敛到一级域 model/

示例#

1
export type Task = {
2
  id: string
3
  title: string
4
  status: 'todo' | 'doing' | 'done'
5
  createdAt: Date
6
}

职责#

• 封装读取链路
• 调用 services/api
• 将 DTO 映射为领域模型
• 管理缓存键与查询行为

职责#

• 封装写入链路
• 写入成功后执行 invalidation

职责#

• 进行页面级或用例级状态编排
• 组合 queries、mutations 与局部 UI 状态

典型用途#

• 页面筛选条件
• 分页状态
• 页面行为封装
• Feature 页面 ViewModel

features/<domain>/index.ts 推荐导出内容（SHOULD）#

• 页面级 Page View
• 面向页面层的编排 composable
• 少量明确需要跨页面复用的 Feature UI
• 必要时导出少量中性帮助类型（如确有必要）
• 一级域场景下，聚合后的子域公开能力

features/<domain>/index.ts 禁止导出内容（MUST）#

• queries/*
• mutations/*
• mappers/*
• 内部 helpers
• 仅供 Feature 内部使用的 partials
• 未明确声明为公开 API 的 components
• 子域内部未收敛的实现细节

features/<domain>/model/index.ts 推荐导出内容（SHOULD）#

• 领域类型
• query keys
• 领域常量
• 明确需要对外稳定暴露的模型契约
• 一级域统一对外的模型边界

导出控制原则#

• Feature 入口应被视为该业务域的”公开 API 面”。
• 入口导出数量应保持克制，避免将整个内部目录结构等价公开。
• 内部实现一旦被公开，后续重构成本会显著上升，因此入口导出必须保持审慎。
• 在大型一级域场景下，应优先由一级域入口聚合子域公开能力，而不是让外部直接面向子域内部文件结构编程。

定义#

页面级业务视图。

使用场景#

• 对应某个路由页的主体内容
• 直接被 src/pages/*Page.vue 组合使用
• 可调用本 Feature 的页面级 composable

示例#

• WorkspaceTasksPageView.vue
• ReviewDetailPageView.vue

定义#

页面中的区块级拼装单元。

使用场景#

• 工具栏
• 筛选区
• 摘要区
• 侧栏区块
• 表单区块
• 页面中的独立大板块

示例#

• WorkspaceTaskToolbar.vue
• WorkspaceSummaryPanel.vue
• ReviewDetailSidebar.vue

定义#

更小粒度的 Feature 内业务组件。

使用场景#

• 表格
• 卡片
• 标签
• 列表项
• 状态显示组件

示例#

• WorkspaceTaskTable.vue
• WorkspaceStatusTag.vue
• ReviewBadge.vue

放入 ui/pages/，如果该组件：#

• 构成某个路由页的主要内容
• 直接被 src/pages/*Page.vue 使用
• 需要组织多个 partials 与 components

放入 ui/partials/，如果该组件：#

• 是页面中的一个大区块
• 自身已组合多个基础组件或业务组件
• 更像页面的一段区域，而不是单一控件

放入 ui/components/，如果该组件：#

• 粒度较小
• 聚焦于一个明确的业务 UI 单元
• 不承担页面区块组织职责

子域下的 UI 组织原则#

• 小型子域可以仅保留少量 ui/ 目录，不强制继续拆分多层结构。
• 只有当子域 UI 已明显形成页面级、区块级、组件级三种不同粒度时，才建议按 pages / partials / components 继续分层。
• Feature UI 分层属于渐进式组织手段，不要求在所有子域中一次到位。

适合放入 Pinia 的状态#

• 用户登录态
• 当前租户 / 工作区上下文
• 主题模式
• 当前语言
• 全局 feature flags
• 系统级偏好设置

不建议放入 Pinia 的状态#

• 列表数据
• 详情数据
• 页面筛选条件
• 页面临时交互态
• 由 query 层可自然管理的数据

上述数据优先放入：

• Feature queries
• Feature composables

推荐使用场景#

• 需要更清晰的数据查询与缓存模型
• 需要替代散落的页面级请求状态管理
• 需要统一处理列表、详情、刷新、失效逻辑

约束#

即使引入 Colada，其使用边界仍应保持不变：

• 查询逻辑仍放在 features/<domain>/queries
• 写入逻辑仍放在 features/<domain>/mutations
• 页面层仍不得直接请求 API

换言之，Colada 改变的是实现工具，不改变分层归属。

A. 全局系统状态 → Pinia（MUST）#

适用于跨页面、跨业务域共享，且具有明显应用级意义的状态。

典型示例：

• 登录态
• 当前用户信息摘要
• 当前租户 / 工作区上下文
• 主题模式
• 当前语言
• 系统级偏好设置
• 全局 feature flags

B. 服务端异步数据 → Query / Colada（MUST）#

适用于来源于服务端、需要缓存、刷新、失效管理的数据。

典型示例：

• 列表数据
• 详情数据
• 统计汇总数据
• 服务端分页数据
• 服务端筛选结果
• 与资源状态强绑定的数据视图

此类数据必须通过 Feature 内 queries/ 管理，而不应直接进入页面或全局 store。

C. 页面/组件临时交互状态 → Feature Composables 或组件本地 state（MUST）#

适用于生命周期较短、仅影响当前页面或局部交互的状态。

典型示例：

• 当前 tab
• 弹窗开关
• 当前展开项
• 输入框临时值
• 当前排序方式
• 页面内筛选面板的本地开关状态

归属原则#

• 只要数据来自服务端并需要与缓存、刷新联动，优先归属 Query / Colada。
• 只要状态具有全局共享属性，归属 Pinia。
• 只要状态仅服务当前页面或当前组件交互，归属 composables 或 local state。

禁止事项（MUST）#

• 不得将列表、详情、分页结果等服务端数据滥用 Pinia 承载。
• 不得将页面临时交互状态上提为全局 store，除非确有跨页面共享需求。
• 不得在页面层直接持有服务端数据管理职责而绕过 Feature 查询层。

首屏加载（SHOULD）#

当页面主体首次加载时，应提供明确的加载态，而不是空白页面或结构闪烁。

局部加载（SHOULD）#

局部刷新或局部区块数据加载时，应优先使用区块级 loading，而非阻断整个页面。

空态（SHOULD）#

当请求成功但无数据时，应提供明确 empty state，而非仅显示空白区域。

错误态（MUST）#

当请求失败时，应至少提供：

• 错误反馈
• 可识别的失败状态
• 合理的重试入口（如适用）

提交态（MUST）#

写入过程中应显式暴露 submitting / pending 状态，用于控制：

• 按钮 disabled
• 防重复提交
• 提交中反馈

乐观更新（MAY）#

仅当业务一致性与回滚逻辑清晰时，允许采用乐观更新。若采用，必须明确失败回滚策略。

统一原则#

• 异步状态应优先在 Feature 层统一建模，再向 UI 暴露。
• 不应由页面层临时拼接异步状态方案。
• 相同类型的页面和区块应尽量保持一致的异步状态表达方式。

定义#

纯基础组件，无业务语义。

示例#

• BaseButton.vue
• BaseInput.vue
• BaseModal.vue
• BaseTable.vue

强约束#

基础组件命名不得出现业务词汇，如：

• task
• review
• workspace
• profile

定义#

跨多个 Feature 复用的轻业务或中性 UI 壳组件。

示例#

• ConfirmDialog.vue
• EmptyState.vue
• LoadingBlock.vue

约束#

若组件已带明显业务语义，应回归对应 Feature，而不是继续放在 shared。

定义#

通用 hooks，不带业务语义。

示例#

• useBoolean.ts
• useDebounce.ts
• usePagination.ts

定义#

纯工具函数。

约束#

若工具函数名称或逻辑已明显依赖业务概念，应放回 Feature。

定义#

环境配置、系统常量、功能开关。

约束#

业务规则不应伪装成全局配置。

若某项常量属于领域规则，应放入 features/<domain>/model/constants.ts。

规则一：页面层禁止直接导入 API#

禁止：

• src/pages/** -> @/services/api/*

规则二：外部禁止导入 Feature 内部实现#

禁止：

• @/features/*/queries/*
• @/features/*/mutations/*
• @/features/*/composables/*
• @/features/*/ui/*

规则三：Shared 禁止依赖 Feature#

禁止：

• components/base -> features
• components/shared -> features
• composables/base -> features
• utils -> features

utils/*（SHOULD）#

优先编写单元测试。

适合验证：

• 日期处理
• 字符串处理
• 对象转换
• 纯函数逻辑

composables/base/*（SHOULD）#

优先编写单元测试。

适合验证：

• 状态切换
• debounce / pagination 等通用行为
• 副作用边界是否正确

features/*/queries/*（SHOULD）#

建议编写逻辑测试或集成测试。

适合验证：

• API 返回与领域模型映射是否正确
• query key 是否符合预期
• 查询条件变化后的结果行为是否正确

features/*/mutations/*（SHOULD）#

建议编写逻辑测试或集成测试。

适合验证：

• 写入参数是否正确
• 成功后 invalidation 是否被触发
• 失败路径反馈是否正确

features/*/composables/*（MUST，关键页面场景）#

页面级编排逻辑应优先测试。

适合验证：

• 页面筛选、分页、排序状态流转
• 页面行为封装
• query / mutation 与页面状态组合是否正确

features/*/ui/components/* 与 ui/partials/*（SHOULD）#

建议进行组件交互测试。

适合验证：

• props / emit 是否符合预期
• 关键交互路径是否可用
• loading / empty / error / disabled 状态是否正确展示

features/*/ui/pages/*（SHOULD）#

建议进行页面主体视图测试。

适合验证：

• 页面主体是否正确组织 partials 与 components
• 页面级 ViewModel 是否正确接入
• 页面主要交互是否可达

pages/*Page.vue（MAY）#

页面层通常较薄，测试优先级低于 Feature page view。

适合验证：

• 路由参数适配
• 多个 Feature page view 的组合关系

router/* 与 layouts/*（SHOULD）#

建议覆盖关键路径测试。

适合验证：

• layout 选择是否正确
• 权限路由跳转是否正确
• 关键守卫逻辑是否正确