92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# 3. namespace
|
||
|
||
namespace 是资源归属、组织与检索的单位。对代码资源，系统使用 namespace key 查找索引，取得对应代码段，并形成可见代码视图。
|
||
|
||
函数、class 和 agent 定义，以及需要独立保存和引用的基础内容，都纳入这一组织体系。资源类别与变量引用见[资源、类型与类](07-types-and-classes.md)；非代码资源的登记和成员定位形式仍待定义，不由代码视图的语法推导。
|
||
|
||
workspace 确定资源的整体归属与授权边界，namespace 组织其内部资源。用户、角色及 r／w／x 分工的主定义见[用户身份与 workspace 权限](02-user-identity.md)。
|
||
|
||
## 3.1 key 格式
|
||
|
||
```text
|
||
workspace handle:第一级namespace.后续namespace
|
||
```
|
||
|
||
key 由一个 workspace handle、一个冒号和至少一个 namespace 路径段组成。路径段之间用点号连接：
|
||
|
||
| key | 结构 |
|
||
| --- | --- |
|
||
| `atelier:shop` | workspace handle 与一级 namespace |
|
||
| `atelier:shop.pricing` | workspace handle 与两级 namespace |
|
||
| `atelier:shop.backend.orders` | workspace handle 与三级 namespace |
|
||
|
||
key 中的 handle 规则见[Workspace handle 与显示名](02-user-identity.md#21-workspace-handle-与显示名)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。
|
||
|
||
## 3.2 最小归属
|
||
|
||
独立登记的资源必须同时具有归属 workspace 和非空 namespace 路径。下列形式缺少必要信息：
|
||
|
||
| 形式 | 缺少的内容 |
|
||
| ---------------------- | ---------------------------------- |
|
||
| `atelier` 或 `atelier:` | namespace 路径 |
|
||
| `:shop` | workspace handle |
|
||
| `atelier.shop.ui` | workspace handle 与 namespace 的分隔冒号 |
|
||
|
||
workspace 显示名不能替代 handle。只有 workspace handle 不是完整 namespace key；workspace 本身的管理入口另行定义。
|
||
|
||
## 3.3 层级语义
|
||
|
||
workspace 承担类似 repository 的整体资源与授权边界。其下第一级 namespace 与所有后续层级具有相同语义，`shop` 不构成额外权限边界或特殊 module 类型。
|
||
|
||
namespace 路径表示组织关系。路径段名 `ui`、`backend`、`data` 或 `agents` 不自动决定执行位置、数据存储、通信方式或语言阶段。
|
||
|
||
父子 namespace 的可见性与成员范围需要独立规则；仅凭路径前缀不能认定读取父级一定包含全部子级代码。
|
||
|
||
## 3.4 可见代码视图
|
||
|
||
代码以独立代码段存储，索引关联完整 key 与代码段。可见代码视图是根据这些成员关系获得的逻辑代码集合：
|
||
|
||
```text
|
||
atelier:shop.pricing
|
||
→ namespace 索引
|
||
→ 对应的独立代码段
|
||
→ 可见代码视图
|
||
```
|
||
|
||
视图可以用于阅读和程序处理，不依赖源码文件的物理路径。S3 承担代码段的存储职责；对象键与语言中的 namespace key 是不同概念，详细约定见[代码存储与视图](../appendices/code-storage-and-views.md)。
|
||
|
||
## 3.5 归属与引用
|
||
|
||
归属 key 定位当前代码，use key 定位它引用的代码。两者使用同一 key 格式，但承担不同职责：
|
||
|
||
```text
|
||
当前代码：market:shop.checkout
|
||
引用目标：atelier:shop.pricing
|
||
```
|
||
|
||
当前代码的 key 由外部上下文提供；引用目标写入正文的 `use` 声明。引用不改变归属，也不自动授予访问权限。下一章说明声明与导入的组织方式。
|
||
|
||
## 3.6 Workspace 与资源成员
|
||
|
||
`atelier:pricing` 与 `atelier:shop.pricing` 都属于 atelier workspace。pricing 与 shop.pricing 是不同的内部路径，增加一层 namespace 不要求额外创建 workspace。
|
||
|
||
| 定位部分 | 职责 |
|
||
| --- | --- |
|
||
| workspace handle | 找到整体归属与授权边界 |
|
||
| namespace 路径 | 找到内部资源组织与检索范围 |
|
||
| 声明名或资源成员标识 | 在该范围内选择具体资源，成员定位形式仍待定义 |
|
||
|
||
成员加入、退出或管理员更换不改变 workspace 中资源的 key；handle 改名与资源迁移是独立操作。历史用户名 key 的迁移与默认 workspace 命名见[规范状态](../appendices/specification-status.md#workspace-名称与生命周期)。
|
||
|
||
## 3.7 整体权限与内部可视域
|
||
|
||
workspace 统一授予资源的 r、w、x 操作权限，不为每个 namespace 或其下级重复配置访问名单。namespace 层级组织内容，读取某层时的视图成员规则仍独立适用；权限覆盖整个 workspace 不表示父级视图自动包含所有下级内容。
|
||
|
||
类型和声明可视域决定程序能否引用一个成员，不代替平台授权。跨 workspace 调用要同时满足目标的语言可见性和执行授权；有权查看源码不自动允许外部程序引用内部成员。
|
||
|
||
`w` 用于编辑代码和资源内容，`x` 用于执行定义好的入口及其业务效果。调用产生业务数据不因此要求调用者取得整个 workspace 的编辑权限。图片等基础内容具有自己的类型用法，workspace 的 `x` 不将它们变成可调用函数。
|
||
|
||
具体角色、执行授权及其与管理能力的关系见[Workspace 角色与授权](02-user-identity.md#27-workspace-角色与授权)。use 的名称引入、声明组合与可视域见下一章。
|
||
|
||
[上一章：用户身份与 workspace 权限](02-user-identity.md) · [下一章：程序结构与导入](04-program-structure.md) · [目录](../README.md)
|