# magic-api-ts

**Repository Path**: xiaobluestarrysky/magic-api-ts

## Basic Information

- **Project Name**: magic-api-ts
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 15
- **Forks**: 4
- **Created**: 2026-08-16
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# magic-api-ts

> 基于 **magic-api** 的 TypeScript 类型增强与 WebStorm 风格开发体验

本项目为 `magic-api` (2.2.2+) 的脚本编辑器（`magic-editor`）注入了一套完整的 **TypeScript 类型系统** 与 **现代 IDE 编辑体验**。它使得原本的 `magic-script` 脚本编写变得像写 TypeScript 一样规范、可控且高效。

---

## 目录

1.  [核心特性](#一核心特性)
2.  [TS 类型系统](#二ts-类型系统)
3.  [智能编码体验](#三智能编码体验)
    *   [智能补全](#31-智能补全)
    *   [实时类型检查](#32-实时类型检查)
    *   [快速修复](#33-快速修复)
4.  [WebStorm 风格编辑](#四webstorm-风格编辑)
    *   [语义着色与语法高亮](#41-语义着色与语法高亮)
    *   [导航与跳转](#42-导航与跳转)
    *   [实时模板](#43-实时模板)
5.  [高级功能](#五高级功能)
    *   [Java 源码查看](#51-java-源码查看)
    *   [多人协同编辑](#52-多人协同编辑)
    *   [Debug 调试内嵌提示](#53-debug-调试内嵌提示)
6.  [工具箱](#六工具箱)
    *   [依赖收集 (collect-libs)](#61-依赖收集工具)

---

## 一、核心特性

*   **类型安全**：强类型的 `type` 定义与模块导入，实现编译期级别的错误检测。
*   **智能提示**：上下文感知的字段补全、类型推断与函数签名提示。
*   **极速修复**：一键修复语法错误（缺逗号、缺字段），支持 Code Action。
*   **WebStorm 级体验**：语义着色、参数内联提示（Inlay Hints）、符号导航、引用统计。
*   **高级协作**：内置多人实时协同编辑与 Java 源码查看能力。

---

## 二、TS 类型系统

### 2.1 定义类型 (`type`)

使用 `type` 关键字定义结构化类型，这是类型系统的基石。

```javascript
// 定义地址类型
type Address = {
    city: string,
    zip: string
}

// 定义主类型，支持可选字段与泛型
type Demo<T = Address> = {
    name: string,
    age: number,
    address: T,          // 引用其他类型
    data?: Data | null,  // 可选字段 (?) 与联合类型
}
```

### 2.2 引入类型模块 (`import '@type/...'})

从 magic-api 后端引入预定义的类型模块，支持命名空间别名。

```javascript
// 引入 demo 模块下的 Demo 类型
import '@type/demo/Demo' as Demo

// 1. 类型注解
const user: Demo = {
    name: "张三",
    age: 18,
    address: { city: "北京", zip: "100000" }
}

// 2. 类型断言 (Cast)
const data = { ... } as Demo
```

> **规范**：别名必须以大写字母开头（例如 `Demo`），以区分类型与普通变量。

---

## 三、智能编码体验

### 3.1 智能补全

编辑器会在你输入时提供精准的补全建议：
*   **字段补全**：在对象字面量 `return {` 或 `const x = {` 中，自动补全已知类型的字段。
*   **嵌套补全**：进入嵌套对象时，自动切换上下文提供子字段补全。
*   **类型补全**：在 `type` 定义或变量注解处，智能提示 `string`, `number` 或已定义的类型名。
*   **Lambda 补全**：函数参数与返回类型处提供类型提示。

### 3.2 实时类型检查

无需运行脚本，编辑过程中即出现红色波浪线报错：
*   **结构校验**：赋值对象缺少必填字段或字段类型不匹配。
*   **语法校验**：检测缺失逗号、括号不匹配等低级错误。
*   **未使用警告**：黄色波浪线提示定义了但未使用的变量或导入。

```javascript
// 错误示例
const obj: Demo = {
    name: 123,           // 错误：期望 string，实际 number
    age: 18
    // 错误：缺少 address 字段
}
```

### 3.3 快速修复 (Ctrl + Enter)

将光标置于错误或警告上，按下 `Ctrl + Enter`，即可呼出快速修复菜单：
*   **插入逗号**：自动修复语法错误。
*   **补全字段**：一键填充所有缺失的类型字段（包含嵌套结构）。
*   **移除未使用**：清理无用变量或 import 语句。

---

## 四、WebStorm 风格编辑

### 4.1 语义着色与语法高亮

基于 AST（抽象语法树）分析，精确区分代码语义，而不仅仅依赖正则匹配：
*   **类型 (Type)**：使用加粗的颜色（如紫色/蓝色），一眼识别类型定义。
*   **函数 (Function)**：区分 `import` 的函数与普通变量。
*   **字段 (Field)**：对象属性使用独特颜色。
*   **参数 (Parameter)**：Lambda 参数使用斜体显示。

### 4.2 导航与跳转

*   **Ctrl + 点击**：跳转到类型定义 (`type`)、模块来源 (`import`) 或 Java 类实现。
*   **符号导航 (Ctrl + Shift + O)**：快速跳转到文件中的类型定义或全局变量。
*   **引用计数 (CodeLens)**：在定义行上方显示引用次数，点击可查看所有引用位置。

### 4.3 实时模板 (Live Templates)

输入缩写即可生成代码片段，极大提升效率：
*   `try` / `tryf`: 生成 `try { ... } catch(e) { ... }` 结构。
*   `fori`: 生成 `for (let i = 0; i < len; i++) { ... }`。
*   `log` / `logd` / `loge`: 生成不同级别的日志输出。

---

## 五、高级功能

### 5.1 Java 源码查看 (Ctrl + Click)

在编写脚本时，如果涉及到 Java 类（例如调用 `new HashMap()`），可以将光标移动到类名上，使用 **Ctrl + 点击** 直接查看该 Java 类的源码（只读）。

*   **依赖配置**：需在 `application.yaml` 中配置 `magic-api.source-libs` 指向包含源码 jar (`-sources.jar`) 的目录。
*   **JDK 内置**：JDK 核心类（如 `String`, `HashMap`）的源码由后端自动读取，无需额外配置。

### 5.2 多人协同编辑

支持多人**实时同步**编辑同一个脚本文件：
*   **实时可见**：A 用户的输入删除，B 用户即时可见。
*   **光标同步**：显示协作者的远程光标与用户名标签。
*   **冲突解决**：基于 CRDT 算法自动合并并发编辑，确保最终内容一致性。

### 5.3 Debug 调试内嵌提示

在断点调试模式下，IDE 会在代码行尾以灰色小字内嵌显示当前变量的实际值（类似 IDEA），无需将鼠标悬停即可快速预览变量状态。

---

## 六、工具箱

### 6.1 依赖收集工具 (collect-libs.bat)

用于收集 Maven 项目的运行时依赖及其源码包，供“Java 源码查看”功能使用。

**使用方法：**
1.  双击运行 `collect-libs.bat`。
2.  在弹窗中选择目标项目的 `pom.xml`。
3.  脚本会自动解析依赖，并将 jar 包和源码复制到 `magic-api-server\jarLib\<项目名>\lib` 目录下。

**命令参数：**
*   `-Pom <path>`: 直接指定 pom.xml 路径。
*   `-Clean`: 复制前清空旧文件。
*   `-h`: 查看帮助。

---

## 配置说明

本项目通常作为 `magic-api` 的插件或模块集成。后端需确保开启以下配置：

```yaml
magic-api:
  # 开启 Java 源码查看 (可选)
  source-libs: ./jarLib/magic-test-web/lib
  # WebSocket 配置 (用于协同编辑与 Debug)
  # ...
```

具体安装与部署请参考 magic-api 官方文档。