Backend Architecture：Route、Service、Repository、Transaction、Observability

Learning outcomes

• 能分辨 route/controller、service、repository 的責任。
• 能解釋 transaction boundary。
• 能處理 external service timeout / retry / idempotency 的基本模型。
• 能設計 request-level observability evidence。

1. 一條可追蹤的 request flow

HTTP Route
   ↓ parse / validate
Authenticated User
   ↓ authorize
Service
   ↓ business rule
Repository
   ↓ SQL / DB client
Database
   ↑ result
Service
   ↑ response model
HTTP Response

2. Route/controller：協調 HTTP，不要塞所有 business rule

async function createCourse(
  req,
  res
) {
  const input =
    parseCourseBody(
      req.body
    );

  if (!input.ok) {
    return res
      .status(400)
      .json(input);
  }

  const course =
    await courseService
      .create({
        user: req.user,
        input: input.data
      });

  res
    .status(201)
    .json(course);
}

3. Service：business operation

async function create({
  user,
  input
}) {
  if (
    await repository
      .existsByTitle(
        user.id,
        input.title
      )
  ) {
    throw new ConflictError();
  }

  return repository.insert({
    ownerId: user.id,
    title: input.title
  });
}

Service 不應依賴 Express req/res 才能運作，這讓 business rule 更容易測。

4. Repository：隔離 persistence details

async function insert(
  course
) {
  return db.query(
    "INSERT ...",
    [...]
  );
}

Repository 不是「一定要有的宗教規則」，但當 DB details 開始污染 business logic 時，這個 boundary 會有價值。

5. Transaction：一個 operation 要嘛全成，要嘛全失敗

BEGIN

insert course
insert audit record
update quota

COMMIT

若三個步驟共同代表一個 business operation，不能接受只完成前兩個。這時 transaction boundary 應包住整個一致性需求。

6. External API：更多 failure modes

7. Observability：production bug 要有 evidence

{
  requestId,
  route,
  userId,
  durationMs,
  dbDurationMs,
  status,
  errorCode
}

不要只記「something failed」。至少要能串 request id、步驟、時間與 error category。

Project checkpoint：Course API final architecture

React Browser
   ↓ HTTPS
Express route
   ↓
request id
validation
authentication
authorization
   ↓
CourseService
   ↓
CourseRepository
   ↓ transaction
Postgres / Supabase
   ↑
response DTO
   ↑
JSON + status
   ↑
Browser

8. 101–106 最後真正學到什麼？