---
title: 工作区（Workspace）
source: https://vjmap.com/guide/service/04-workspace.html
---

# 工作区（Workspace）

工作区是 vjmap 的**命名空间机制**：不同工作区下的图、符号、KV 存储、全文索引**互相隔离**。

## 1. 概念

- **默认工作区**：不带名字；URL 用 `/api/v1/map/...` 前缀
- **命名工作区**：人为创建；URL 变为 `/api/v1/workspace/{name}/...` 前缀
- 工作区本身也有状态：`{name, description, createTime, ...}`，由 `/api/v1/service/getWorkspace` 列出
- 一个 token 理论上可访问所有工作区；实际权限由 `AuthorityId` 决定

## 2. 切换工作区（SDK）

### Python

```python
svc = Vjmap("http://127.0.0.1:27660/api/v1", token)
svc.switch_workspace("team_a")          # 之后所有 map_url / cmd_url 都会自动带上 /workspace/team_a
svc.open_map("finance", "v1", mapopenway="Memory")  # → /api/v1/workspace/team_a/cmd/openmap/finance/v1
svc.switch_workspace("")                # 切回默认工作区
```

### Node

```javascript
svc.switchWorkspace('team_a');
await svc.openMap({ mapid: 'finance', version: 'v1', mapopenway: 'Memory' });
svc.switchWorkspace('');
```

## 3. 生命周期接口

| # | 操作 | URL | 方法 |
|---|------|------|------|
| 1 | 列出 | `/api/v1/service/getWorkspace` | GET |
| 2 | 创建 | `/api/v1/service/workspaceCreate` | POST |
| 3 | 修改 | `/api/v1/service/workspaceModify` | POST |
| 4 | 删除 | `/api/v1/service/workspaceDelete/{name}` | DELETE |
| 5 | 状态 | `/api/v1/service/workspaceStatus` | GET |

详细字段、响应示例请看 [`api/07-workspace.md`](api/07-workspace.md) 。

## 4. 底层 URL 改写规则

- web服务网关把 `/api/v1/workspace/{name}/*` 改写成 **带 workspace 参数**的 `/api/v1/map/*`；图形服务不感知名字，由网关保证隔离
- 因此凡是 `/api/v1/map/` 下的路径都能在 `/workspace/{name}/` 下一模一样使用
- `/api/v1/service/*`（全局 KV、符号库、全文搜索）**不受**工作区前缀影响；它们的隔离通过各自的 `workspace` 参数实现（大部分接口接受 `workspace=` query）

## 5 反模式

- 不要在**热路径**里频繁调用 `switch_workspace()` 再立刻发请求；SDK 内部只是改前缀，没 IO，但业务代码可能会混乱。建议**一个 svc 实例绑一个 workspace**。
- 不要把 `workspace` 和 `mapid` 拼到一起当复合键用；保持**每图一个 mapid，workspace 单独字段**。