Tách prototype thành module với rủi ro tối giản

Tại sao prototype lại rủi ro khi thay đổi

Một prototype có cảm giác nhanh vì mọi thứ nằm gần nhau. Một route gọi tới database, định dạng response, rồi UI render nó. Tốc độ đó là thật, nhưng ẩn một chi phí: khi nhiều tính năng hơn được thêm vào, con đường “nhanh ban đầu” trở thành con đường mà mọi thứ phụ thuộc vào.

Thứ thường hỏng đầu tiên thường không phải mã mới. Mà là những giả định cũ.

Một thay đổi nhỏ ở route có thể âm thầm thay đổi dạng response và làm hỏng hai màn hình. Một truy vấn “tạm” bị copy vào ba nơi bắt đầu trả về dữ liệu hơi khác nhau, và không ai biết cái nào đúng.

Đó cũng là lý do các rewrite lớn thất bại dù có ý tốt. Chúng thay đổi cấu trúc và hành vi cùng lúc. Khi bug xuất hiện, bạn không biết lỗi do một quyết định thiết kế mới hay do một sai sót cơ bản. Niềm tin giảm, scope phình to, và rewrite lê thê.

Refactor rủi ro thấp nghĩa là giữ thay đổi nhỏ và có thể hoàn nguyên. Bạn nên có thể dừng sau bất kỳ bước nào và vẫn có app hoạt động. Các quy tắc thực tế thì đơn giản:

• Một mục tiêu rõ ràng cho mỗi thay đổi (di chuyển mã, không thay đổi chức năng)
• Chu kỳ ngắn để bạn có thể kiểm thử cùng luồng người dùng mỗi lần
• Kế hoạch rollback nhàm chán mà bạn có thể thực hiện nhanh
• Mã mới sống cạnh mã cũ cho tới khi nó chứng minh được mình

Routes, services, truy cập DB và UI rối khi mỗi layer bắt đầu làm việc của layer khác. Tháo gỡ không phải để đuổi theo "kiến trúc hoàn hảo." Mà là di chuyển từng sợi một.

Đặt quy tắc trước khi chạm vào mã

Xem refactor như một cuộc dời chỗ, không phải tu sửa toàn bộ. Giữ hành vi giống nhau, và làm cho cấu trúc dễ thay đổi hơn sau này. Nếu bạn vừa “cải thiện” tính năng vừa tái tổ chức, bạn sẽ mất dấu những gì bị hỏng và vì sao.

Ghi ra những thứ chưa đổi. Các mục "chưa đổi" phổ biến: tính năng mới, redesign UI, thay đổi schema DB, và công việc tối ưu hiệu năng. Ranh giới này giữ công việc ở mức rủi ro thấp.

Chọn một “golden path” và bảo vệ nó. Chọn một thứ người dùng làm hàng ngày, như:

sign in -> create item -> view list -> edit item -> save

Bạn sẽ chạy lại luồng này sau mỗi bước nhỏ. Nếu nó vẫn hành xử như trước, bạn có thể tiếp tục.

Thống nhất rollback trước commit đầu tiên. Rollback nên nhàm chán: một git revert, một feature flag ngắn hạn, hoặc snapshot nền tảng bạn có thể khôi phục. Nếu bạn đang xây dựng trong Koder.ai, snapshots và rollback có thể là mạng lưới an toàn hữu ích khi bạn tái tổ chức.

Giữ định nghĩa xong việc (definition of done) nhỏ cho mỗi giai đoạn. Bạn không cần checklist dài, chỉ đủ để ngăn "di chuyển + thay đổi" lẻn vào:

• Cùng input tạo cùng output (bao gồm lỗi và trạng thái rỗng)
• Golden path vượt qua kiểm thử thủ công nhanh (hoặc kiểm tra tự động nhỏ)
• Thay đổi nằm trong phạm vi giai đoạn (chỉ routes, hoặc chỉ services)
• Rollback được kiểm chứng ít nhất một lần (bạn thực sự thử)
• Một ghi chú ngắn giải thích cái gì đã di chuyển và giờ nằm ở đâu

Nếu prototype có một file duy nhất xử lý routes, query DB và định dạng UI, đừng tách mọi thứ cùng lúc. Trước hết, chỉ di chuyển các handler route vào một thư mục và giữ logic như cũ, ngay cả khi nó bị copy. Khi điều đó ổn định, rút services và truy cập DB ở giai đoạn sau.

Kiểm kê nhanh: routes, màn hình, và đường dẫn dữ liệu

Trước khi bắt đầu, vẽ sơ qua những gì đang có hôm nay. Đây không phải redesign. Mà là bước an toàn để bạn có thể thực hiện các bước nhỏ, có thể hoàn nguyên.

Liệt kê mỗi route hoặc endpoint và viết một câu ngắn về chức năng của nó. Bao gồm route UI (pages) và API (handlers). Nếu bạn dùng generator chat và xuất mã, xử lý nó giống nhau: inventory nên khớp những gì người dùng thấy với thứ mã thực sự chạm tới.

Một inventory nhẹ mà hữu ích:

• Route/endpoint + mục đích (ví dụ: "/checkout" hiển thị form thanh toán)
• UI screen/component kích hoạt nó
• Quy tắc nghiệp vụ liên quan (giá, validate, phân quyền)
• Bảng DB bị chạm và kiểu truy cập (read/write/transaction)
• Các bản sao và lặp lại (cùng validation copy vào 3 file)

Với mỗi route, viết một ghi chú “data path” nhanh:

UI event -> handler -> logic -> DB query -> response -> UI update

Khi làm, gắn tag các khu vực rủi ro để không vô tình thay đổi chúng khi dọn dẹp mã gần đó:

• Thanh toán và billing
• Auth, session, roles
• Database migrations và seed scripts
• Background jobs và scheduled tasks
• Bất cứ thứ gì chạy trong transaction

Cuối cùng, phác thảo bản đồ module mục tiêu đơn giản. Giữ nó nông. Bạn đang chọn điểm đến, không xây hệ thống mới:

routes/handlers, services, db (queries/repositories), ui (screens/components)

Nếu bạn không thể giải thích một đoạn mã nên nằm ở đâu, đó là ứng viên tốt để refactor sau, khi bạn có nhiều tự tin hơn.

Giai đoạn 1: Ổn định routes mà không đổi logic

Bắt đầu bằng cách xem routes (hoặc controllers) như một ranh giới, không phải nơi để cải thiện code. Mục tiêu là giữ mọi request hành xử như trước trong khi đặt endpoints ở nơi dễ dự đoán.

Tạo một module mỏng cho từng khu vực tính năng, như users, orders, hoặc billing. Tránh “dọn dẹp khi di chuyển.” Nếu bạn đổi tên, tái tổ chức file và rewrite logic trong cùng một commit, rất khó tìm lỗi gì gây ra.

Một trình tự an toàn:

• Nhóm các route handler hiện có theo feature, ngay cả khi bên trong lộn xộn.
• Chỉ di chuyển wiring code trước: đọc params, validate cơ bản, gọi cùng các hàm cũ bạn đã tin tưởng.
• Giữ responses y nguyên: status code, thông báo lỗi, và payload shape.
• Thêm một kiểm tra nhỏ cho golden path mỗi route (một gọi happy-path phải vẫn chạy).

Ví dụ cụ thể: nếu bạn có một file duy nhất với POST /orders parse JSON, check fields, tính tổng, ghi vào DB, và trả order mới, đừng rewrite nó. Trích handler vào orders/routes và gọi logic cũ, như createOrderLegacy(req). Module route mới trở thành cửa trước; logic legacy giữ nguyên tạm thời.

Nếu bạn làm việc với mã sinh (ví dụ backend Go được tạo trong Koder.ai), tư duy không đổi. Đặt mỗi endpoint ở nơi dễ dự đoán, bao bọc logic legacy, và chứng minh request phổ biến vẫn thành công.

Giai đoạn 2: Kéo business logic vào services

Routes không phải nơi thích hợp cho business rules. Chúng phát triển nhanh, trộn lo ngại, và mỗi thay đổi có cảm giác rủi ro vì bạn đụng tới mọi thứ cùng lúc.

Định nghĩa một hàm service cho mỗi hành động hướng người dùng. Route nên chỉ thu thập inputs, gọi service, và trả response. Giữ các lần gọi DB, quy tắc giá, và kiểm tra permission ra khỏi routes.

Các hàm service dễ lý giải hơn khi chúng làm một việc, có input rõ và output rõ. Nếu bạn cứ thêm “và thêm nữa…”, hãy tách nó.

Một pattern đặt tên thường dùng:

• CreateOrder(input) -> order
• CancelOrder(orderId, actor) -> result
• GetOrderSummary(orderId) -> summary

Giữ quy tắc trong services, không để UI quyết định. Ví dụ: thay vì UI disable nút vì “premium users chỉ được tạo 10 order”, hãy enforce quy tắc đó trong service. UI vẫn có thể hiển thị thông báo thân thiện, nhưng quy tắc chỉ ở một nơi.

Trước khi chuyển tiếp, thêm vừa đủ test để làm thay đổi có thể hoàn nguyên:

• Một test happy-path tạo/cập nhật đúng
• Một test error-path (thiếu trường bắt buộc, permission denied)

Nếu bạn dùng công cụ tăng tốc như Koder.ai để generate hoặc lặp nhanh, services trở thành mỏ neo của bạn. Routes và UI có thể thay đổi, nhưng quy tắc vẫn ổn định và dễ test.

Giai đoạn 3: Cô lập truy cập cơ sở dữ liệu một cách an toàn

Khi routes ổn định và services tồn tại, ngừng để database "ở khắp nơi." Che các query thô sau một lớp data access nhỏ, nhàm chán.

Tạo một module nhỏ (repository/store/queries) cung cấp vài hàm với tên rõ, như GetUserByEmail, ListInvoicesForAccount, hoặc SaveOrder. Đừng theo đuổi sự tinh tế ở đây. Hướng tới một nơi rõ ràng cho mỗi chuỗi SQL hoặc gọi ORM.

Giữ giai đoạn này chỉ về cấu trúc. Tránh thay đổi schema, tinh chỉnh index, hoặc migration “nhân tiện.” Những việc đó xứng đáng là thay đổi riêng có kế hoạch và rollback.

Đặt transaction ở một chỗ

Một mùi prototype phổ biến là transactions rải rác: một hàm bắt transaction, hàm khác âm thầm mở của riêng nó, và xử lý lỗi khác nhau theo file.

Thay vào đó, tạo một entry point chạy callback trong transaction, và cho repositories chấp nhận context transaction.

Giữ các bước nhỏ:

• Di chuyển một query tại một thời điểm vào repository, giữ input/output như trước.
• Để services gọi trực tiếp hàm repository mới (không logic thừa).
• Tập trung begin/commit/rollback transaction trong một helper.
• Chuẩn hoá mapping lỗi (ví dụ “not found” vs “unexpected error”).

Ví dụ, nếu “Create Project” insert project rồi insert default settings, hãy bọc cả hai trong helper transaction. Nếu có lỗi giữa chừng, bạn sẽ không có project tồn tại mà thiếu settings.

Khi services phụ thuộc vào interface thay vì DB client cụ thể, bạn có thể test hầu hết hành vi mà không cần DB thật. Điều đó giảm nỗi sợ — mục tiêu của giai đoạn này.

Giai đoạn 4: Dọn dẹp component UI mà không redesign

Dọn dẹp UI không phải để làm đẹp. Mà để làm screens dự đoán được và giảm side-effect bất ngờ.

Nhóm mã UI theo feature, không theo loại kỹ thuật. Một folder feature có thể chứa screen, component nhỏ, và helper cục bộ. Khi thấy markup lặp (cùng hàng nút, card, hay trường form), trích nó ra, nhưng giữ markup và style như trước.

Giữ props đơn giản. Truyền chỉ những gì component cần (strings, ids, booleans, callbacks). Nếu bạn truyền một object lớn “phòng khi cần”, hãy định nghĩa shape nhỏ hơn.

Di chuyển cuộc gọi API ra khỏi component UI. Ngay cả với service layer, UI thường chứa logic fetch, retry, và mapping. Tạo một client module nhỏ cho từng feature (hoặc từng miền API) trả về dữ liệu sẵn cho màn hình.

Rồi làm cho loading và xử lý lỗi nhất quán giữa các màn hình. Chọn một pattern và tái sử dụng: trạng thái loading dễ dự đoán, thông báo lỗi nhất quán với một hành động thử lại, và empty state giải thích bước tiếp theo.

Sau mỗi extraction, kiểm tra nhanh giao diện màn hình bạn vừa chạm. Nhấn các hành động chính, refresh trang, và kích hoạt một trường hợp lỗi. Các bước nhỏ thắng các rewrite UI lớn.

Một ví dụ thực tế: refactor một feature end to end

Giả sử một prototype nhỏ với ba màn hình: sign in, list items, edit item. Nó hoạt động, nhưng mỗi route trộn auth checks, business rules, SQL, và trạng thái UI. Mục tiêu là biến chỉ feature này thành một module sạch với thay đổi bạn có thể rollback.

Trước và sau: cái gì di chuyển tới đâu

Trước, logic “items” có thể rải rác:

server/
  main.go
  routes.go
  handlers.go          # sign in + items + random helpers
  db.go                # raw SQL helpers used everywhere
web/
  pages/
    SignIn.tsx
    Items.tsx          # fetch + state + form markup mixed

Sau, hành vi vẫn thế, nhưng ranh giới rõ ràng hơn:

server/
  routes/
    items_routes.go
  handlers/
    items_handler.go
  services/
    items_service.go
  repositories/
    items_repo.go
web/
  pages/
    Items.tsx
  components/
    ItemForm.tsx

Một lần chạy end to end (nhỏ, có thể hoàn nguyên)

Bắt đầu bằng cách di chuyển mã mà không đổi logic. Giữ tên hàm và dạng trả về như trước, nên rollback chủ yếu là di chuyển file.

Refactor một route trước. Handler chỉ nên xử lý HTTP, không rules hay SQL:

// handlers/items_handler.go
func (h *ItemsHandler) UpdateItem(w http.ResponseWriter, r *http.Request) {
  userID := h.auth.UserIDFromRequest(r) // same auth logic as before
  itemID := mux.Vars(r)["id"]

  var in UpdateItemInput
  json.NewDecoder(r.Body).Decode(&in)

  item, err := h.itemsService.UpdateItem(r.Context(), userID, itemID, in)
  if err != nil { writeError(w, err); return }
  writeJSON(w, item)
}

Tiếp theo, kéo rules nghiệp vụ vào service. Đặt các kiểm tra như “user chỉ được edit item của chính họ” hoặc “tên không được rỗng.” Service gọi repository để làm việc DB:

// services/items_service.go
func (s *ItemsService) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  if strings.TrimSpace(in.Name) == "" { return Item{}, ErrInvalidName }
  return s.repo.UpdateItem(ctx, userID, itemID, in)
}

Rồi cô lập truy cập DB vào hàm repository:

// repositories/items_repo.go
func (r *ItemsRepo) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  row := r.db.QueryRowContext(ctx,
    `UPDATE items SET name=$1 WHERE id=$2 AND user_id=$3 RETURNING id, name`,
    in.Name, itemID, userID,
  )
  var it Item
  err := row.Scan(&it.ID, &it.Name)
  return it, err
}

Phía UI, giữ layout trang, nhưng trích markup form lặp lại vào component dùng chung cho cả flow “new” và “edit”:

• pages/Items.tsx giữ việc fetch và navigation
• components/ItemForm.tsx phụ trách input fields, thông báo validate và nút submit

Nếu bạn dùng Koder.ai (koder.ai), export source code có thể hữu ích trước các refactor sâu hơn, và snapshots/rollback giúp bạn phục hồi nhanh khi một di chuyển gặp trục trặc.

Bẫy thường gặp làm tăng rủi ro

Rủi ro lớn nhất là trộn “di chuyển” với “thay đổi.” Khi bạn relocate file và rewrite logic trong cùng commit, bug ẩn trong diff ồn ào. Giữ các di chuyển nhàm chán: cùng hàm, cùng input, cùng output, chỉ là chỗ ở mới.

Một bẫy khác là dọn dẹp làm thay đổi hành vi. Đổi tên biến thì ok; đổi khái niệm thì không. Nếu status chuyển từ string sang số, bạn đã thay đổi sản phẩm chứ không chỉ mã. Làm việc đó sau với test rõ ràng và phát hành có chủ ý.

Mẫu lặng lẽ tạo rắc rối

Ban đầu, bạn dễ bị cám dỗ tạo một cây thư mục to và nhiều lớp “cho tương lai.” Điều đó thường làm bạn chậm lại và khó thấy công việc thực sự ở đâu. Bắt đầu với ranh giới nhỏ nhất hữu dụng, rồi mở rộng khi tính năng kế tiếp bắt buộc.

Cũng cảnh giác việc UI trực tiếp truy cập DB (hoặc gọi query thô qua helper). Nó có vẻ nhanh, nhưng khiến mỗi màn hình chịu trách nhiệm về permission, data rules và xử lý lỗi.

Những thứ làm tăng rủi ro:

• Commit refactor lớn chạm nhiều file và thay đổi logic cùng lúc
• Shapes trả về chung thay đổi mà không cập nhật mọi caller
• Thêm layer mới không có lý do rõ
• Xử lý lỗi bị phẳng hoá (mọi thứ thành null hoặc thông báo chung)

Ví dụ nhỏ: nếu một màn hình mong { ok: true, data } nhưng service mới trả { data } và throw on errors, nửa app có thể ngừng hiển thị thông báo thân thiện. Giữ shape cũ ở ranh giới trước, rồi migrate từng caller.

Kiểm tra nhanh trước khi sang giai đoạn tiếp theo

Trước khi bước tiếp, chứng minh bạn không làm hỏng trải nghiệm chính. Chạy cùng golden path mỗi lần (sign in, create item, view, edit, delete). Tính nhất quán giúp bạn phát hiện regressions nhỏ.

Dùng cổng go/no-go sau mỗi giai đoạn:

• Golden path vẫn chạy end to end, bao gồm các lỗi phổ biến.
• Routes/controllers mỏng: đọc input, gọi một service, trả response.
• Services có thể dùng lại: gọi từ routes, background job, hoặc UI mà không biết về HTTP.
• Truy cập DB được tập trung với một pattern transaction và xử lý lỗi nhất quán.
• Rollback nhanh và đã được kiểm chứng.

Nếu một điều thất bại, dừng và sửa trước khi xây thêm. Vết nứt nhỏ trở thành vết to sau này.

Bài drill “chúng ta có thể undo không?” nhanh

Ngay sau khi merge, dành năm phút xác minh bạn có thể lùi lại:

• Revert commit gần nhất trên branch local và xác nhận app khởi động và golden path chạy.
• Tắt đường dẫn mã mới (feature flag, config switch, hoặc điều kiện) và xác nhận hành vi cũ vẫn tồn tại.
• Kiểm tra logs và các ghi DB cho golden path một lần để đảm bảo hành vi lưu trữ không đổi.

Các bước tiếp theo: giữ mô-đun khi sản phẩm lớn dần

Chiến thắng không phải là lần dọn đầu tiên. Chiến thắng là giữ được cấu trúc khi bạn thêm tính năng. Bạn không đuổi theo kiến trúc hoàn hảo. Bạn làm cho các thay đổi tương lai có thể dự đoán được, nhỏ, và dễ undo.

Chọn module tiếp theo dựa trên tác động và rủi ro, không phải vì phiền. Mục tiêu tốt là phần người dùng chạm thường xuyên, nơi hành vi đã được hiểu. Để lại những khu vực chưa rõ hoặc mong manh cho tới khi bạn có test tốt hơn hoặc câu trả lời sản phẩm rõ hơn.

Giữ cadence đơn giản: PR nhỏ di chuyển một việc, vòng review ngắn, phát hành thường xuyên, và quy tắc dừng (nếu scope phình, tách nó và ship mảnh nhỏ hơn).

Trước mỗi giai đoạn, đặt một điểm rollback: git tag, release branch, hoặc build deployable bạn biết hoạt động. Nếu bạn xây trong Koder.ai, Planning Mode có thể giúp bạn giai đoạn hoá thay đổi để không vô tình refactor ba layer cùng lúc.

Một quy tắc thực tế cho kiến trúc ứng dụng mô-đun: mỗi tính năng mới theo cùng ranh giới. Routes giữ mỏng, services nắm rules nghiệp vụ, code DB sống một chỗ, và component UI tập trung hiển thị. Khi tính năng mới phá vỡ các quy tắc đó, refactor sớm khi thay đổi còn nhỏ.