Week 3: Development Tools & Practices

🎯 Learning Objectives学习目标

Configure a GitLab CI pipeline that keeps the main branch green using runners and staged jobs. 配置 GitLab CI 流水线，使用 runner 与多阶段任务确保 main 分支始终为绿色状态。
Apply TypeScript static verification to protect against invalid runtime input and document error handling. 运用 TypeScript 静态验证防止非法运行时输入，并编写清晰的错误处理。
Enforce linting standards (ESLint/Prettier) to maintain consistent, readable code across a team. 使用 ESLint/Prettier 维护团队代码风格一致性与可读性。
Design and test HTTP/Express servers, issuing automated requests via Jest + sync-request-curl. 设计并测试 HTTP/Express 服务器，通过 Jest + sync-request-curl 自动化发起请求。

🧠 Core Concepts from Lectures 3.1–3.4核心概念（第3.1–3.4讲）

🔄 Continuous Integration Pipelines持续集成流水线

Add a .gitlab-ci.yml that runs on every push. GitLab takes the commit, spins up a runner, executes the defined stages (e.g. npm install, npm run test) and reports a green tick when successful.

在每次 push 时执行 .gitlab-ci.yml。GitLab 获取提交、启动 runner 执行各阶段（如 npm install、npm run test），成功后给予绿色勾选。

Stages: checks, deploy etc. (Lecture 3.1)阶段：checks、deploy 等（3.1 讲）
Runners execute pipelines on isolated machines.Runner 在独立机器上运行流水线。
Rule: main branch must stay green.原则：主分支必须保持绿色。

✅ Static Verification & Type Safety静态验证与类型安全

TypeScript guards against unexpected inputs. Moving runtime checks into compile-time prevents silent failures and documents expectations.

TypeScript 可防止意外输入，将运行时检查前移到编译期，避免无声失败并记录预期。

Lecture 3.2 emphasises guarding function signatures.第 3.2 讲强调保护函数签名。
Combine zod or manual guards with TS types.结合 zod 或手动 guard 与 TS 类型。
Report descriptive errors for invalid arguments.针对无效参数给出描述性错误信息。

🧹 Linting & Style Automation代码检查与风格自动化

ESLint/Prettier enforce style rules so code remains human-friendly—indentation, naming, unused variables, maximum complexity.

ESLint/Prettier 可强制风格规则，让代码更易读——缩进、命名、未使用变量、复杂度上限。

Lecture 3.3 contrasts “bad” vs “good” style.第 3.3 讲比较“坏代码”与“好代码”。
Integrate linting into CI to block failing merges.将 Lint 集成进 CI，阻止不合格合并。
Prettier complements ESLint for formatting.Prettier 辅助 ESLint 做格式化。

🌐 HTTP Servers & TestingHTTP 服务器与测试

Express servers respond to HTTP requests; use sync-request-curl and Jest to script integration tests for each endpoint.

Express 服务器响应 HTTP 请求；通过 sync-request-curl 与 Jest 编写每个端点的集成测试。

Lecture 3.4 + 4.2 cover networks, routes, middleware, CRUD.3.4 与 4.2 讲覆盖网络、路由、中间件、CRUD。
Track status codes (200/400/403/500) and HTTPS behaviour.关注状态码（200/400/403/500）与 HTTPS 行为。
Document endpoints via Swagger/OpenAPI.使用 Swagger/OpenAPI 描述端点。

🧩 Exam & Assessment Alignment与考试/作业的对应关系

Iteration 1/2 Pipelines — Labs & project marking check the presence of a working GitLab CI pipeline (Quiz 3, Assignment rubric). 迭代 1/2 流水线 — 实验与项目评分会检查 GitLab CI 是否正常（第3周测验、作业评分标准）。
Static Verification — Type safety questions frequently appear in mid-term short answers. Expect to explain how TS prevents runtime crashes. 静态验证 — 类型安全题常见于期中简答，需说明 TS 如何避免运行时崩溃。
Lint Rules — Multiple-choice/short answer items ask about why linting catches defects (e.g. unused vars, inconsistent formatting). Lint 规则 — 选择/简答题常问 Lint 如何捕捉缺陷（如未使用变量、格式不一）。
HTTP Status & Testing — Assignment Iteration 2 requires automated Jest requests verifying every REST route, including error branches. HTTP 状态与测试 — 作业迭代 2 要求用 Jest 自动请求验证每个 REST 路由及错误分支。

🧪 Worked Examples示例讲解

1. GitLab CI PipelineGitLab CI 流水线Lecture 3.1

image: comp1531/basic:latest

stages:
  - checks

install:
  stage: checks
  script:
    - npm install

unit-tests:
  stage: checks
  script:
    - npm run test
  only:
    - main
    - merge_requests

Keep each stage idempotent and fast; merge requests must show a green pipeline before approval.

保持每个阶段幂等且快速；合并请求需在审批前显示绿色流水线。

2. Type-Safe Helper类型安全的辅助函数Lecture 3.2

type RepeatArgs = {
  repeat: number;
  value: string;
};

export function manyString({ repeat, value }: RepeatArgs): string {
  if (!Number.isInteger(repeat) || repeat < 0) {
    throw new Error('repeat must be a non-negative integer');
  }
  return value.repeat(repeat);
}

Prefer descriptive arguments and guards instead of silently returning unexpected values.

使用描述性参数与 guard，避免静默返回异常结果。

3. Express Route with Jest TestExpress 路由及 Jest 测试Lecture 3.4 & 4.2

// server.ts
app.post('/auth/login', (req, res) => {
  const { email, password } = req.body;
  if (!isValid(email, password)) {
    return res.status(400).json({ error: 'Invalid credentials' });
  }
  return res.status(200).json({ token: issueToken(email) });
});

// requests.test.ts
import request from 'sync-request-curl';

describe('POST /auth/login', () => {
  test('rejects wrong password', () => {
    const res = request('POST', `${BASE_URL}/auth/login`, {
      json: { email: 'test@unsw.edu.au', password: 'wrong' },
    });
    expect(res.statusCode).toBe(400);
  });
});

Automated requests keep regressions out of the server. Status codes form part of assessment marking.

自动请求可防止服务器回归。状态码也是评分要点。

🛠 Tutorial 3 Integration教程 3 对接

📁 Working with Multiple Files多文件拆分

Move datastore logic into src/dataStore.ts and expose typed helpers.将数据存储逻辑拆入 src/dataStore.ts 并暴露类型化 helper。
Export functions for reuse in routes and tests.导出函数供路由与测试复用。
Document each helper’s error cases.记录每个 helper 的错误情况。

📦 npm Packagesnpm 包

Install sync-request-curl for scripted HTTP calls.安装 sync-request-curl 用于脚本化 HTTP 请求。
Use dotenv to manage secrets locally.用 dotenv 管理本地密钥。
Add npm scripts (npm run lint, npm run test) for CI.新增 npm 脚本（如 npm run lint、npm run test）供 CI 调用。

🧪 Testing Strategy测试策略

Black-box tests target observable behaviour (Lecture 3.3).黑盒测试关注可观察行为（3.3 讲）。
Use test.only/test.skip while iterating.迭代开发时使用 test.only/test.skip。
Check both success and error responses.为成功与错误响应都编写测试。

🎧 Playlist Mini-System播放列表小系统

Design typed interfaces for addUser, addSong, listPlaylist.为 addUser、addSong、listPlaylist 设计类型接口。
Return meaningful HTTP errors (400/403/500) as per tutorial brief.按教程要求返回有意义的 HTTP 错误（400/403/500）。
Document endpoints in Swagger for teammates.用 Swagger 记录端点，便于团队协作。

🧭 Practice Tasks实践任务

Pipeline Drill: Fork the lab repository, add the CI sample above, and ensure every MR shows a green tick. 流水线演练： fork 实验仓库，加入上述 CI 样例，并确保每次 MR 都显示绿色勾选。
Type Guard Kata: Rewrite at least two helper functions in TypeScript, adding guards + unit tests for bad inputs. 类型守卫练习： 将至少两个辅助函数改写为 TypeScript，添加守卫及坏输入单测。
Lint & Fix: Run npm run lint, record two warnings, and commit the fixes. Lint 修复： 执行 npm run lint，记录两条警告并提交修复。
HTTP Test Harness: Write Jest + sync-request-curl tests covering both success & failure responses for each endpoint. HTTP 测试工具： 使用 Jest + sync-request-curl 为每个端点编写成功与失败两类测试。

📘 Week 3 Quiz Preview第3周测验预览

Identify when a CI pipeline should fail vs pass (Lecture 3.1 scenarios). 判断 CI 流水线应当失败或通过的情况（3.1 讲场景）。
Explain how TypeScript prevents bugs when functions receive optional parameters. 说明 TypeScript 如何在函数接收可选参数时防止缺陷。
Choose appropriate ESLint rules to catch stylistic problems. 选择合适的 ESLint 规则捕捉风格问题。
Diagnose HTTP status codes for REST APIs under different error conditions. 分析 REST API 在不同错误情况下对应的 HTTP 状态码。

Head to Week 3 Quiz and look for questions labelled CI, TS, Lint, HTTP. 前往第3周测验，关注标记为 CI、TS、Lint、HTTP 的题目。

📝 Summary & Further Reading小结与延伸阅读

CI + linting keep the repository shippable; failing pipelines block merges. CI 与 Lint 保证仓库可发布；流水线失败应阻止合并。
Static types turn runtime surprises into compile-time fixes. 静态类型将运行时的意外转换为编译期修复。
HTTP endpoints must be documented, tested, and return precise status codes. HTTP 端点需记录、测试并返回精确的状态码。

Recommended reading: Lecture 3.1 Slides, Lecture 3.2 Slides, Lecture 3.3 Slides, Lecture 3.4 Slides. 推荐阅读：第3.1讲 PPT、第3.2讲 PPT、第3.3讲 PPT、第3.4讲 PPT。