TypeScript 开发指南

my-app/
├── package.json               // 依赖与脚本
├── tsconfig.json              // TypeScript 编译配置
├── src/                       // 源码
│   ├── index.ts               // 入口
│   ├── models/                // 数据模型 / 类型
│   ├── services/              // 业务逻辑
│   ├── utils/                 // 工具函数
│   └── types/                 // 全局类型声明（.d.ts）
├── tests/                     // 测试
├── node_modules/              // 依赖（不提交）
└── dist/                      // 编译输出

# 安装 TypeScript 7（Go 原生编译器）
npm install -D typescript@7

# 初始化项目
npm init -y
tsc --init                 # 生成 tsconfig.json（已内置 strict:true）

# 编译（7.0 默认多线程并行，默认用 4 个 checker）
tsc                        # 读 tsconfig.json 编译，8~12x 加速
tsc --watch                # 监听模式（基于 Parcel watcher，更稳定）

# 并行调优（可选）
tsc --checkers 8           # 提高类型检查并行度（默认4，加快构建）
tsc --singleThreaded       # 完全禁用并行（调试/CI 低内存）

interface Person {
  name: string
  age: number
}

// 不需要 implements Person！只要结构匹配就能赋值
let p: Person = {
  name: 'Alice',
  age: 18
}

// class 也能赋值给 interface（结构匹配即可）
class User {
  name: string = ''
  age: number = 0
}
let u: Person = new User()  // ✅ 结构匹配

// 直接传对象字面量
function printPerson(person: Person): void {
  console.log(person.name)
}
printPerson({ name: 'Bob', age: 20 })  // ✅ 合法

// any：放弃类型检查（尽量不用）
let a: any = 1
a.anything()        // 不报错，危险

// unknown：安全的"未知类型"，需收窄后才能用
let u: unknown = 1
// u.toFixed()       // ❌ 报错，unknown 不能直接调用方法

// 收窄后才能用
if (typeof u === 'number') {
  u.toFixed()   // ✅ 收窄为 number
}

// ❌ as 断言：丢失字面量精度，且不验证
const config1 = { port: 8080 } as Config
// config1.port 类型是 number，不是 8080

// ✅ satisfies：保留字面量精度，且强制满足 Config
const config2 = { port: 8080 } satisfies Config
// config2.port 类型是 8080（字面量），同时保证符合 Config 结构

// 编译期就能发现结构错误
const bad = { port: '8080' } satisfies Config  // ❌ 编译错误

// 严格模式下不能给非空类型赋 null/undefined
let name: string = null   // ❌ 编译错误（strictNullChecks）

// 显式标注可空
let name2: string | null = null

// 空值合并运算符（类似 Optional.orElse）
let display = name2 ?? 'unknown'

// 可选链（类似 Optional.map）
let len = name2?.length   // name2 为 null 时返回 undefined，不报错

// 非空断言（告诉编译器"我确定不为 null"）
let len2 = name2!.length   // 有风险，尽量用可选链替代

let name = 'Alice'
let age = 18

// 模板字符串（反引号）
let msg = `Name: ${name}, Age: ${age}`

// 多行字符串
let html = `<div>
  <p>${name}</p>
</div>`

// 表达式嵌入
let result = `Total: ${items.reduce((a, b) => a + b, 0)}`

class Counter {
  count: number = 0

  // ❌ 普通函数：this 不指向 Counter
  bad() {
    setTimeout(function() {
      this.count++  // this 是 undefined 或全局对象！
    }, 1000)
  }

  // ✅ 箭头函数：this 继承自 Counter
  good() {
    setTimeout(() => {
      this.count++  // this 指向 Counter 实例 ✅
    }, 1000)
  }
}

// Java 写法（冗长）
// class User { private String name; private int age;
//   public User(String name, int age) { this.name = name; this.age = age; } }

// TS 简写：构造器参数前加修饰符，自动声明并赋值字段
class User {
  constructor(public name: string, private age: number) {}
}

const u = new User('Alice', 18)
u.name  // ✅ 自动成为 public 字段
// u.age  // ❌ private，外部不可访问

let arr: number[] = [3, 1, 2]

// 添加/删除
arr.push(4)           // 尾部添加
arr.pop()              // 尾部删除
arr.unshift(0)         // 头部添加
arr.shift()             // 头部删除
arr.splice(1, 1)        // 索引1删1个

// 查找
arr.includes(2)         // true
arr.indexOf(2)           // 2
arr.find(x => x > 1)       // 3（第一个满足条件的）

// 变换
arr.sort((a, b) => a - b) // 排序（原地）
arr.reverse()            // 反转（原地）
let sliced = arr.slice(0, 2)  // 截取（返回新数组）

// 展开（类似 Java 的 list.addAll）
let combined = [...arr, 5, 6]

// 解构赋值
let [a, b, ...rest] = [1, 2, 3, 4]
// a=1, b=2, rest=[3,4]

// 字面量类型：值本身作为类型
let direction: 'north' | 'south' | 'east' | 'west' = 'north'
direction = 'up'  // ❌ 编译错误

// 类型别名
type Direction = 'north' | 'south' | 'east' | 'west'

// 枚举替代（Java 的 enum）
enum Status { Active = 'ACTIVE', Inactive = 'INACTIVE' }
const s: Status = Status.Active

interface User {
  id: number
  name: string
  email: string
}

// 映射类型：批量转换所有属性
type ReadonlyUser = { readonly [K in keyof User]: User[K] }
type NullableUser = { [K in keyof User]: User[K] | null }

// 内置映射类型（高频使用）
type A = Partial<User>    // 所有属性可选
type B = Required<User>   // 所有属性必填
type C = Pick<User, 'id' | 'name'>  // 挑选部分属性
type D = Omit<User, 'email'>   // 排除部分属性
type E = Record<'a' | 'b', number> // { a: number; b: number }

// 条件类型（类型层面的 if/else）
type IsString<T> = T extends string ? 'yes' : 'no'
type R1 = IsString<string>  // 'yes'
type R2 = IsString<number>  // 'no'

interface Config {
  host: string
  port: number
}

// keyof：获取对象的所有键（Java 需反射）
type ConfigKeys = keyof Config  // 'host' | 'port'

// 泛型 + keyof + 泛型推断：类型安全的属性访问
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key]
}

const c: Config = { host: 'localhost', port: 8080 }
const h = getProperty(c, 'host')  // h: string ✅
// getProperty(c, 'xxx')  // ❌ 编译错误，'xxx' 不是 Config 的键

// 泛型参数默认值
function wrap<T = string>(v: T): T { return v }

// 创建 Promise（类似 CompletableFuture.supplyAsync）
function fetchUser(id: number): Promise<User> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ name: 'Alice', age: 18 })
      } else {
        reject(new Error('Invalid id'))
      }
    }, 1000)
  })
}

// 方式1：then/catch（类似 CompletableFuture 链）
fetchUser(1)
  .then(user => console.log(user.name))
  .catch(err => console.error(err))

// 方式2：async/await（推荐，更可读）
async function main() {
  try {
    const user = await fetchUser(1)
    console.log(user.name)
  } catch (e) {
    console.error(`Failed: ${e}`)
  }
}

async function loadAll() {
  // 并发发起 3 个请求，全部完成后继续
  const [user, posts, friends] = await Promise.all([
    fetchUser(1),
    fetchPosts(1),
    fetchFriends(1)
  ])
  // 三个结果同时可用
}

// 任一完成即返回（谁先到用谁，类似竞速）
const fastest = await Promise.race([
  fetchFromCache(),
  fetchFromNetwork()
])

// 全部成功才成功，否则 reject（类似 allOf + 整体失败）
const results = await Promise.allSettled([
  task1(), task2(), task3()
])

{
  "compilerOptions": {
    // ── 以下为 TS 7 默认值（无需显式写）──
    // "strict": true,            // 默认开启（6+）
    // "module": "esnext",        // 默认（7）
    // "target": <当前稳定ES>,     // 默认（7）
    // "esModuleInterop": true,   // 强制（7）
    // "alwaysStrict": true,      // 固定（7）

    // ── 你可能仍需显式设置的 ──
    "moduleResolution": "bundler",   // 或 "nodenext"（Node 20+）
    "noUncheckedIndexedAccess": true,  // arr[0] 类型为 T | undefined
    "exactOptionalPropertyTypes": true, // 区分 ?: 与 | undefined
    "noImplicitOverride": true,       // 强制写 override（对应 Java）
    "verbatimModuleSyntax": true,    // import type 必须显式
    "outDir": "./dist",
    "sourceMap": true
  },
  // TS 7: rootDir 默认 ./，需显式指定源码目录
  "include": ["src"]
}