Windsurf

Windsurf Editor 是一款人工智慧驅動的程式碼編輯器，旨在透過自動化重複性的編碼任務來提高生產力。當它與 Prisma（一套強大且型別安全的資料庫工作流程工具組）搭配使用時，將成為管理與優化資料庫 Schema、查詢與資料植入（Seeding）的強大解決方案。

本指南提供了將 Prisma 與 Windsurf 有效結合的詳細說明，協助您：

• 透過 .windsurfrules 定義專案專屬的最佳實踐。
• 運用 Windsurf 的環境感知能力。
• 根據您的資料庫生成客製化的 Schema、查詢與植入資料。

注意

雖然本指南聚焦於 Windsurf，但這些模式同樣適用於任何 AI 編輯器。如果您希望我們為您慣用的工具製作指南，請透過 X (Twitter) 告訴我們！

Prisma MCP 伺服器

Prisma 提供了自己的 模型上下文協議 (MCP) 伺服器，讓您可以管理 Prisma Postgres 資料庫、建立資料庫 Schema 模型，甚至透過對話來執行遷移（Migrations）。

透過 Windsurf 外掛程式添加 Prisma MCP 伺服器

您可以透過 Windsurf MCP 外掛商店 添加 Prisma MCP 伺服器。

新的 MCP 外掛可以從外掛商店 (Plugin Store) 添加。您可以點擊 Cascade 面板右上角選單中的外掛 (Plugins) 圖示，或是從風衝設定 (Windsurf Settings) > Cascade > 外掛 (Plugins) 部分存取。只需在外掛商店中搜尋 Prisma 並安裝 Prisma 外掛即可。

注意

您也可以手動添加 Prisma MCP 伺服器。請參閱此處以了解如何手動將 MCP 伺服器添加到 Windsurf。

使用 .windsurfrules 定義專案專屬規則

Windsurf 中的 .windsurfrules 檔案 可讓您強制執行針對 Prisma 專案量身打造的最佳實踐與開發標準。透過定義明確且一致的規則，您可以確保 Windsurf 生成乾淨、易於維護且符合專案規範的程式碼，並將手動調整的需求降至最低。

若要實施這些規則，請在專案根目錄建立一個 .windsurfrules 檔案。以下是設定範例：

.windsurfrules 檔案範例

.windsurfrules

You are a senior TypeScript/JavaScript programmer with expertise in Prisma, clean code principles, and modern backend development.
Generate code, corrections, and refactorings that comply with the following guidelines:
TypeScript General Guidelines
Basic Principles
- Use English for all code and documentation.
- Always declare explicit types for variables and functions.
  - Avoid using "any".
  - Create precise, descriptive types.
- Use JSDoc to document public classes and methods.
- Maintain a single export per file.
- Write self-documenting, intention-revealing code.
Nomenclature
- Use PascalCase for classes and interfaces.
- Use camelCase for variables, functions, methods.
- Use kebab-case for file and directory names.
- Use UPPERCASE for environment variables and constants.
- Start function names with a verb.
- Use verb-based names for boolean variables:
  - isLoading, hasError, canDelete
- Use complete words, avoiding unnecessary abbreviations.
  - Exceptions: standard abbreviations like API, URL
  - Accepted short forms: 
    - i, j for loop indices
    - err for errors
    - ctx for contexts
Functions
- Write concise, single-purpose functions.
  - Aim for less than 20 lines of code.
- Name functions descriptively with a verb.
- Minimize function complexity:
  - Use early returns.
  - Extract complex logic to utility functions.
- Leverage functional programming techniques:
  - Prefer map, filter, reduce.
  - Use arrow functions for simple operations.
  - Use named functions for complex logic.
- Use object parameters for multiple arguments.
- Maintain a single level of abstraction.
Data Handling
- Encapsulate data in composite types.
- Prefer immutability.
  - Use readonly for unchanging data.
  - Use as const for literal values.
- Validate data at the boundaries.
Error Handling
- Use specific, descriptive error types.
- Provide context in error messages.
- Use global error handling where appropriate.
- Log errors with sufficient context.
Prisma-Specific Guidelines
Schema Design
- Use meaningful, domain-driven model names.
- Leverage Prisma schema features:
  - Use @id for primary keys.
  - Use @unique for natural unique identifiers.
  - Utilize @relation for explicit relationship definitions.
- Keep schemas normalized and DRY.
- Use meaningful field names and types.
- Implement soft delete with deletedAt timestamp.
- Use Prisma's native type decorators.
Prisma Client Usage
- Always use type-safe Prisma client operations.
- Prefer transactions for complex, multi-step operations.
- Handle optional relations explicitly.
- Use Prisma's filtering and pagination capabilities.
Database Migrations
- Create migrations for schema changes.
- Use descriptive migration names.
- Review migrations before applying.
- Never modify existing migrations.
- Keep migrations idempotent.
Error Handling with Prisma
- Catch and handle Prisma-specific errors:
  - PrismaClientKnownRequestError
  - PrismaClientUnknownRequestError
  - PrismaClientValidationError
- Provide user-friendly error messages.
- Log detailed error information for debugging.
Testing Prisma Code
- Use in-memory database for unit tests.
- Mock Prisma client for isolated testing.
- Test different scenarios:
  - Successful operations
  - Error cases
  - Edge conditions
- Use factory methods for test data generation.
- Implement integration tests with actual database.
Performance Considerations
- Use select and include judiciously.
- Avoid N+1 query problems.
- Use findMany with take and skip for pagination.
- Leverage Prisma's distinct for unique results.
- Profile and optimize database queries.
Security Best Practices
- Never expose raw Prisma client in APIs.
- Use input validation before database operations.
- Implement row-level security.
- Sanitize and validate all user inputs.
- Use Prisma's built-in protections against SQL injection.
Coding Style
- Keep Prisma-related code in dedicated repositories/modules.
- Separate data access logic from business logic.
- Create repository patterns for complex queries.
- Use dependency injection for Prisma services.
Code Quality
- Follow SOLID principles.
- Prefer composition over inheritance.
- Write clean, readable, and maintainable code.
- Continuously refactor and improve code structure.
Development Workflow
- Use version control (Git).
- Implement comprehensive test coverage.
- Use continuous integration.
- Perform regular code reviews.
- Keep dependencies up to date.

此檔案可確保程式碼生成的一致性與可維護性，減少手動介入，同時提升專案品質。

運用 Windsurf 的環境感知能力

Windsurf 的 環境感知 (context-awareness) 功能讓您可以利用專案檔案與外部資源，增強 AI 對專案的理解。透過將 Prisma Schema 與相關文件納入環境脈絡，您可以讓 Windsurf 根據您的資料庫 Schema 生成更精確的查詢、測試與植入資料。

包含額外的 Prisma 資源

Windsurf 內建了對常見函式庫的知識，但您可以透過明確引用外部 Prisma 資源來進一步增強其理解能力。這對於保持技術更新或為程式碼生成與最佳實踐提供權威依據特別有用。

例如，您可以引用：

• Prisma 更新日誌 (Changelog)
• Prisma 部落格
• Prisma 文件

在請求中引用資源：

當要求產生程式碼、解釋或審核時，請附上相關 Prisma 資源的連結，並指定應將其作為參考依據。

Generate a migration script using best practices from prisma.io/docs.

要求持久的感知能力：

要求 Windsurf 在您專案中所有與 Prisma 相關的工作中，始終參考特定資源。

Always use the Prisma Changelog at prisma.io/changelog for Prisma updates in this project.

要求定期更新：

如果您希望 Windsurf 檢查更新或新功能，請明確提出要求。

Before suggesting Prisma code, check the latest changes from prisma.io/changelog.

透過直接在請求或專案指南中引用外部資源，您可以確保 Windsurf 運用最新且相關的 Prisma 資訊。

將 Schema 作為上下文使用

開箱即用，Windsurf 會自動將當前檔案、其他開啟的檔案以及程式碼庫中已建立索引的部分作為上下文。為了確保 Cascade 能充分利用您的 Prisma Schema，請保持 schema.prisma 檔案在編輯器中開啟或釘選。

生成 Prisma Schema

Windsurf 可以根據高階描述生成 Prisma Schema，讓您快速為資料庫模型建立穩固基礎。透過提供清晰詳細的提示（Prompt），Windsurf 能依照您的需求產生客製化的 Prisma Schema。無論您需要通用的基礎架構或是針對特定使用案例的精確架構，Windsurf 都能精準達成。以下是一個提示與其對應結果的範例：

注意

大型語言模型 (LLM) 即便使用相同的提示，每次產生的結果也可能有所不同。

"Create a Prisma schema for a SaaS app using PostgreSQL as a provider with `User`, `Organization`, and `Subscription` models, ensuring all models include `createdAt` and `updatedAt` DateTime fields with defaults, a soft-delete `deletedAt` field, and proper relationships between entities."

schema.prisma

generator client {
  provider = "prisma-client"
  output   = "./generated"
}

datasource db {
  provider = "postgresql"
}

model User {
  id             Int           @id @default(autoincrement())
  email          String        @unique
  name           String
  password       String
  createdAt      DateTime      @default(now())
  updatedAt      DateTime      @updatedAt
  deletedAt      DateTime?
  organization   Organization  @relation(fields: [organizationId], references: [id])
  organizationId Int
  role           UserRole      @default(MEMBER)
}

model Organization {
  id           Int           @id @default(autoincrement())
  name         String
  slug         String        @unique
  subscription Subscription?
  users        User[]
  createdAt    DateTime      @default(now())
  updatedAt    DateTime      @updatedAt
  deletedAt    DateTime?
}

model Subscription {
  id             Int              @id @default(autoincrement())
  organization   Organization     @relation(fields: [organizationId], references: [id])
  organizationId Int              @unique
  plan           SubscriptionPlan
  status         SubscriptionStatus @default(ACTIVE)
  startDate      DateTime
  endDate        DateTime?
  createdAt      DateTime         @default(now())
  updatedAt      DateTime         @updatedAt
  deletedAt      DateTime?
}

enum UserRole {
  ADMIN
  MEMBER
}

enum SubscriptionPlan {
  FREE
  BASIC
  PREMIUM
  ENTERPRISE
}

enum SubscriptionStatus {
  ACTIVE
  CANCELED
  EXPIRED
  PAST_DUE
}

生成 Prisma 查詢

Windsurf 可協助您建立針對 Prisma Schema 客製化的查詢，無論是基本的資料檢索還是複雜的優化操作。為獲得最佳效果，請專注於撰寫清晰、具體的提示，明確定義您的需求，例如：要包含的欄位、應用的條件以及要跨越的關係。這能確保 Windsurf 生成準確、高效且型別安全的查詢。以下是一個提示與其產生的查詢範例：

"Generate a query to retrieve all User records associated with an Organization that has an `active` Subscription, while excluding any records where the `deletedAt` field is set."

const activeUsers = await prisma.user.findMany({
  where: {
    deletedAt: null,
    organization: {
      deletedAt: null,
      subscription: {
        deletedAt: null,
        status: 'ACTIVE'
      }
    }
  },
  include: {
    organization: {
      include: {
        subscription: true
      }
    }
  },
  orderBy: {
    createdAt: 'desc'
  },
  skip: 0,
  take: 10
});

使用 Windsurf 建立植入 (Seed) 檔案

撰寫植入腳本可能是一個繁瑣的過程，但 Windsurf 能透過快速生成結構化且組織良好的植入程式碼來簡化它。透過提供明確的指令，您可以引導 Windsurf 建立腳本，以真實的資料填充您的資料庫，包括處理 Schema 中定義的關係與複雜結構。以下是一個提示與其產生的植入腳本範例：

"Generate code to populate the Prisma schema with realistic data for the User, Organization, and Subscription models, ensuring all necessary fields are included."

seed.ts

import {
  PrismaClient,
  UserRole,
  SubscriptionPlan,
  SubscriptionStatus,
} from "../prisma/generated/client";

const prisma = new PrismaClient();

async function main() {
  // Clear existing data
  await prisma.user.deleteMany();
  await prisma.subscription.deleteMany();
  await prisma.organization.deleteMany();

  const organizations = [
    {
      name: "Tech Innovators",
      slug: "tech-innovators",
      subscription: {
        plan: SubscriptionPlan.ENTERPRISE,
        status: SubscriptionStatus.ACTIVE,
        startDate: new Date("2024-01-01"),
      },
      users: [
        {
          name: "Emma Thompson",
          email: "emma@techinnovators.com",
          role: UserRole.ADMIN,
          password: "password123",
        },
        {
          name: "Michael Chen",
          email: "michael@techinnovators.com",
          role: UserRole.MEMBER,
          password: "password123",
        },
      ],
    },
    {
      name: "Digital Solutions",
      slug: "digital-solutions",
      subscription: {
        plan: SubscriptionPlan.PREMIUM,
        status: SubscriptionStatus.ACTIVE,
        startDate: new Date("2024-01-15"),
      },
      users: [
        {
          name: "Sarah Wilson",
          email: "sarah@digitalsolutions.com",
          role: UserRole.ADMIN,
          password: "password123",
        },
        {
          name: "James Miller",
          email: "james@digitalsolutions.com",
          role: UserRole.MEMBER,
          password: "password123",
        },
      ],
    },
    {
      name: "Cloud Systems",
      slug: "cloud-systems",
      subscription: {
        plan: SubscriptionPlan.BASIC,
        status: SubscriptionStatus.ACTIVE,
        startDate: new Date("2024-02-01"),
      },
      users: [
        {
          name: "David Garcia",
          email: "david@cloudsystems.com",
          role: UserRole.ADMIN,
          password: "password123",
        },
        {
          name: "Lisa Wang",
          email: "lisa@cloudsystems.com",
          role: UserRole.MEMBER,
          password: "password123",
        },
      ],
    },
    {
      name: "Data Analytics Co",
      slug: "data-analytics",
      subscription: {
        plan: SubscriptionPlan.PREMIUM,
        status: SubscriptionStatus.ACTIVE,
        startDate: new Date("2024-01-10"),
      },
      users: [
        {
          name: "Alex Johnson",
          email: "alex@dataanalytics.com",
          role: UserRole.ADMIN,
          password: "password123",
        },
        {
          name: "Rachel Kim",
          email: "rachel@dataanalytics.com",
          role: UserRole.MEMBER,
          password: "password123",
        },
      ],
    },
    {
      name: "Smart Solutions",
      slug: "smart-solutions",
      subscription: {
        plan: SubscriptionPlan.FREE,
        status: SubscriptionStatus.ACTIVE,
        startDate: new Date("2024-02-15"),
      },
      users: [
        {
          name: "Daniel Brown",
          email: "daniel@smartsolutions.com",
          role: UserRole.ADMIN,
          password: "password123",
        },
        {
          name: "Maria Rodriguez",
          email: "maria@smartsolutions.com",
          role: UserRole.MEMBER,
          password: "password123",
        },
      ],
    },
  ];

  for (const org of organizations) {
    const createdOrg = await prisma.organization.create({
      data: {
        name: org.name,
        slug: org.slug,
        subscription: {
          create: {
            plan: org.subscription.plan,
            status: org.subscription.status,
            startDate: org.subscription.startDate,
          },
        },
      },
    });

    for (const user of org.users) {
      await prisma.user.create({
        data: {
          name: user.name,
          email: user.email,
          password: user.password,
          role: user.role,
          organizationId: createdOrg.id,
        },
      });
    }
  }

  console.log("Seed data created successfully");
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

使用 Prisma VS Code 擴充功能管理您的資料庫

Prisma VS Code 外掛 是建構 Prisma Postgres 應用程式的強大工具。您也可以透過安裝此延伸模組在 Windsurf 中使用它。它提供了專用的使用者介面，用於管理本地與遠端的 Prisma Postgres 實例，使檢視、建立、刪除實例、將本地資料庫推送至雲端以及視覺化您的 Schema 變得輕而易舉。

資料庫管理 UI

憑藉其內建的資料庫管理介面，Prisma VS Code 外掛讓您可以直接在編輯器內輕鬆操作本地與遠端的 Prisma Postgres 實例。

工作流程

此 UI 支援以下工作流程：

• 進行身份驗證
• 檢視、建立及刪除 Prisma Postgres 實例（本機與遠端）
• 「推送到雲端 (Push to cloud)」：輕鬆部署本機 Prisma Postgres 實例
• 透過嵌入式 Prisma Studio 查看並編輯資料
• 視覺化您的資料庫 schema

使用方法

若要透過 Prisma VS Code 擴充功能中的 UI 管理 Prisma Postgres 實例：

1. 請確保已安裝最新版的 Prisma VS Code 擴充功能
2. 在活動列 (Activity Bar) 中找到 Prisma 標誌
3. 點擊開始使用請先登入 (Sign in to get started) 按鈕
4. 進行身份驗證使用登入提示，然後選擇一個目標 工作區 (workspace)

內建 Prisma Studio

除了管理資料庫執行個體之外，Prisma VS Code 擴充功能還將 Prisma Studio 直接嵌入您的編輯器中，讓您能輕鬆地直接在 Windsurf 內部對資料庫進行建立、更新和刪除操作。請按照這些簡單步驟開始使用。

額外資源

在 Windsurf 中使用 Prisma 可以加快開發速度，同時確保資料庫程式碼簡潔且易於維護。若要繼續學習：

• Windsurf 文件
• Prisma 文件

與 Prisma 保持聯繫

透過以下方式與我們聯繫，繼續您的 Prisma 旅程： 我們的活躍社群。保持資訊靈通、參與其中，並與其他開發者合作

• 在 X 上關注我們 以獲取公告、現場活動和實用技巧。
• 加入我們的 Discord 提出問題、與社群對話，並透過對話獲得積極支援。
• 在 YouTube 上訂閱 查看教學、演示和直播。
• 在 GitHub 上交流 透過為存放庫加星標、報告問題或為 issue 做出貢獻。

我們衷心感謝您的參與，並期待您成為我們社群的一份子！