gcp-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GCP Development Best Practices

GCP开发最佳实践

Overview

概述

This skill provides comprehensive guidelines for developing applications on Google Cloud Platform (GCP), covering serverless computing, data services, Infrastructure as Code with Terraform, and security best practices.

本技能提供了在Google Cloud Platform (GCP)上开发应用的全面指南，涵盖无服务器计算、数据服务、基于Terraform的基础设施即代码以及安全最佳实践。

Core Principles

核心原则

Write clean, well-structured code using GCP client libraries
Use Infrastructure as Code (Terraform) for all infrastructure management
Follow Google Cloud security best practices and compliance guidelines
Implement comprehensive logging with Cloud Logging and monitoring with Cloud Monitoring

使用GCP客户端库编写整洁、结构良好的代码
使用基础设施即代码（Terraform）管理所有基础设施
遵循Google Cloud安全最佳实践和合规指南
通过Cloud Logging实现全面日志记录，通过Cloud Monitoring实现监控

Code Organization and Structure

代码组织与结构

Terraform Module Structure

Terraform模块结构

infrastructure/
├── main.tf           # Primary resources
├── variables.tf      # Input variables
├── outputs.tf        # Output values
├── versions.tf       # Provider versions
├── terraform.tfvars  # Variable values
└── modules/
    ├── compute/
    ├── storage/
    └── networking/

infrastructure/
├── main.tf           # 核心资源
├── variables.tf      # 输入变量
├── outputs.tf        # 输出值
├── versions.tf       # 提供商版本
├── terraform.tfvars  # 变量值
└── modules/
    ├── compute/
    ├── storage/
    └── networking/

Application Structure

应用结构

src/
├── functions/        # Cloud Functions
├── services/         # Cloud Run services
├── shared/           # Shared utilities
└── tests/            # Test files

src/
├── functions/        # Cloud Functions
├── services/         # Cloud Run 服务
├── shared/           # 共享工具库
└── tests/            # 测试文件

Cloud Functions Guidelines

Cloud Functions 指南

Function Configuration

函数配置

typescript

import { HttpFunction } from '@google-cloud/functions-framework';

export const helloWorld: HttpFunction = async (req, res) => {
  try {
    // Validate request
    if (req.method !== 'POST') {
      res.status(405).send('Method Not Allowed');
      return;
    }

    // Business logic
    const result = await processRequest(req.body);

    res.status(200).json(result);
  } catch (error) {
    console.error('Function error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
};

typescript

import { HttpFunction } from '@google-cloud/functions-framework';

export const helloWorld: HttpFunction = async (req, res) => {
  try {
    // 验证请求
    if (req.method !== 'POST') {
      res.status(405).send('Method Not Allowed');
      return;
    }

    // 业务逻辑
    const result = await processRequest(req.body);

    res.status(200).json(result);
  } catch (error) {
    console.error('Function error:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
};

Best Practices

最佳实践

Use 2nd generation Cloud Functions for better performance
Set appropriate memory and timeout limits
Use environment variables for configuration
Implement proper error handling and logging
Use connection pooling for database connections

使用第二代Cloud Functions以获得更好的性能
设置合适的内存和超时限制
使用环境变量存储配置信息
实现完善的错误处理和日志记录
对数据库连接使用连接池

Cloud Run Guidelines

Cloud Run 指南

Container Best Practices

容器最佳实践

Use distroless or minimal base images
Implement health check endpoints
Handle SIGTERM for graceful shutdown
Use Cloud Run services for HTTP workloads
Use Cloud Run jobs for batch processing

使用无发行版（distroless）或轻量基础镜像
实现健康检查端点
处理SIGTERM信号以实现优雅停机
对HTTP工作负载使用Cloud Run服务
对批处理任务使用Cloud Run作业

Dockerfile Example

Dockerfile示例

dockerfile

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
CMD ["dist/index.js"]

dockerfile

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
CMD ["dist/index.js"]

Service Configuration

服务配置

yaml

undefined

yaml

undefined

service.yaml

apiVersion: serving.knative.dev/v1 kind: Service metadata: name: my-service spec: template: spec: containers: - image: gcr.io/PROJECT_ID/my-service resources: limits: memory: 512Mi cpu: '1' env: - name: NODE_ENV value: production

undefined

undefined

Firestore Guidelines

Firestore 指南

Data Modeling

数据建模

Design collections around query patterns
Use subcollections for hierarchical data
Implement composite indexes for complex queries
Use batch writes for multiple document updates

围绕查询模式设计集合
对层级数据使用子集合
为复杂查询实现复合索引
对多文档更新使用批量写入

Best Practices

最佳实践

typescript

import { Firestore } from '@google-cloud/firestore';

const db = new Firestore();

// Use transactions for atomic operations
await db.runTransaction(async (transaction) => {
  const docRef = db.collection('users').doc(userId);
  const doc = await transaction.get(docRef);

  if (!doc.exists) {
    throw new Error('User not found');
  }

  transaction.update(docRef, {
    lastLogin: Firestore.FieldValue.serverTimestamp()
  });
});

typescript

import { Firestore } from '@google-cloud/firestore';

const db = new Firestore();

// 使用事务实现原子操作
await db.runTransaction(async (transaction) => {
  const docRef = db.collection('users').doc(userId);
  const doc = await transaction.get(docRef);

  if (!doc.exists) {
    throw new Error('User not found');
  }

  transaction.update(docRef, {
    lastLogin: Firestore.FieldValue.serverTimestamp()
  });
});

BigQuery Guidelines

BigQuery 指南

Query Best Practices

查询最佳实践

Use partitioned and clustered tables
Avoid SELECT * in production queries
Use parameterized queries to prevent SQL injection
Implement query caching where appropriate

使用分区表和聚类表
在生产查询中避免使用SELECT *
使用参数化查询防止SQL注入
在合适场景下启用查询缓存

Cost Optimization

成本优化

Set up budget alerts
Use slot reservations for predictable workloads
Archive old data to Cloud Storage
Use materialized views for repeated queries

设置预算告警
对可预测工作负载使用插槽预留
将旧数据归档到Cloud Storage
对重复查询使用物化视图

Cloud Storage Guidelines

Cloud Storage 指南

Bucket Configuration

存储桶配置

Use uniform bucket-level access
Enable versioning for important data
Set lifecycle rules for automatic cleanup
Use signed URLs for temporary access

使用统一存储桶级访问控制
为重要数据启用版本控制
设置生命周期规则自动清理数据
使用签名URL提供临时访问权限

Best Practices

最佳实践

typescript

import { Storage } from '@google-cloud/storage';

const storage = new Storage();
const bucket = storage.bucket('my-bucket');

// Generate signed URL for upload
const [url] = await bucket.file('uploads/file.pdf').getSignedUrl({
  version: 'v4',
  action: 'write',
  expires: Date.now() + 15 * 60 * 1000, // 15 minutes
  contentType: 'application/pdf',
});

typescript

import { Storage } from '@google-cloud/storage';

const storage = new Storage();
const bucket = storage.bucket('my-bucket');

// 生成用于上传的签名URL
const [url] = await bucket.file('uploads/file.pdf').getSignedUrl({
  version: 'v4',
  action: 'write',
  expires: Date.now() + 15 * 60 * 1000, // 15分钟
  contentType: 'application/pdf',
});

Terraform Best Practices

Terraform 最佳实践

Provider Configuration

提供商配置

hcl

terraform {
  required_version = ">= 1.0"

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }

  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "terraform/state"
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

hcl

terraform {
  required_version = ">= 1.0"

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }

  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "terraform/state"
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

Module Best Practices

模块最佳实践

Use versioned modules from Terraform Registry
Lock provider versions for consistency
Use workspaces for environment separation
Store state in Cloud Storage with encryption

使用Terraform Registry中的版本化模块
锁定提供商版本以保证一致性
使用工作区实现环境隔离
将状态存储在加密的Cloud Storage中

Security Best Practices

安全最佳实践

IAM Configuration

IAM配置

Use service accounts with minimal permissions
Implement Workload Identity for GKE
Use IAM Conditions for fine-grained access
Regular audit with Policy Analyzer

使用权限最小化的服务账号
为GKE实现Workload Identity
使用IAM条件实现细粒度访问控制
定期使用Policy Analyzer进行审计

Secret Management

密钥管理

typescript

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const client = new SecretManagerServiceClient();

async function getSecret(secretName: string): Promise<string> {
  const [version] = await client.accessSecretVersion({
    name: `projects/PROJECT_ID/secrets/${secretName}/versions/latest`,
  });

  return version.payload?.data?.toString() || '';
}

typescript

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const client = new SecretManagerServiceClient();

async function getSecret(secretName: string): Promise<string> {
  const [version] = await client.accessSecretVersion({
    name: `projects/PROJECT_ID/secrets/${secretName}/versions/latest`,
  });

  return version.payload?.data?.toString() || '';
}

Network Security

网络安全

Use VPC Service Controls for sensitive data
Implement Cloud Armor for DDoS protection
Use Private Google Access for internal services
Configure firewall rules with least privilege

对敏感数据使用VPC服务控制
实现Cloud Armor以抵御DDoS攻击
对内部服务使用Private Google Access
按照最小权限原则配置防火墙规则

Deployment Best Practices

部署最佳实践

Blue/Green Deployments

蓝绿部署

Use traffic splitting in Cloud Run
Implement health checks before traffic shift
Have rollback strategy ready
Use Cloud Deploy for managed deployments

在Cloud Run中使用流量拆分
在流量切换前执行健康检查
准备回滚策略
使用Cloud Deploy进行托管式部署

CI/CD with Cloud Build

基于Cloud Build的CI/CD

yaml

undefined

yaml

undefined

cloudbuild.yaml

steps:

name: 'node:20' entrypoint: npm args: ['ci']
name: 'node:20' entrypoint: npm args: ['test']
name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service', '.']
name: 'gcr.io/cloud-builders/docker' args: ['push', 'gcr.io/$PROJECT_ID/my-service']
name: 'gcr.io/google.com/cloudsdktool/cloud-sdk' entrypoint: gcloud args:
- 'run'
- 'deploy'
- 'my-service'
- '--image=gcr.io/$PROJECT_ID/my-service'
- '--region=us-central1'

undefined

steps:

name: 'node:20' entrypoint: npm args: ['ci']
name: 'node:20' entrypoint: npm args: ['test']
name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service', '.']
name: 'gcr.io/cloud-builders/docker' args: ['push', 'gcr.io/$PROJECT_ID/my-service']
name: 'gcr.io/google.com/cloudsdktool/cloud-sdk' entrypoint: gcloud args:
- 'run'
- 'deploy'
- 'my-service'
- '--image=gcr.io/$PROJECT_ID/my-service'
- '--region=us-central1'

undefined

Observability

可观测性

Cloud Logging

Use structured logging in JSON format
Include trace IDs for distributed tracing
Set up log-based metrics for monitoring
Configure log sinks for long-term storage

使用JSON格式的结构化日志
包含跟踪ID以支持分布式追踪
设置基于日志的指标用于监控
配置日志接收器实现长期存储

Cloud Monitoring

Create SLIs and SLOs for services
Set up alerting policies for critical metrics
Use custom metrics for business KPIs
Implement uptime checks for endpoints

为服务创建SLI和SLO
为关键指标设置告警策略
为业务KPI使用自定义指标
为端点实现可用性检查

Cloud Trace

typescript

import { TraceExporter } from '@google-cloud/opentelemetry-cloud-trace-exporter';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new BatchSpanProcessor(new TraceExporter())
);
provider.register();

typescript

import { TraceExporter } from '@google-cloud/opentelemetry-cloud-trace-exporter';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new BatchSpanProcessor(new TraceExporter())
);
provider.register();

Debugging Strategies

调试策略

Use Cloud Debugger for production debugging
Implement error reporting with Error Reporting
Use Cloud Profiler for performance analysis
Test locally with emulators before deployment

使用Cloud Debugger进行生产环境调试
结合Error Reporting实现错误上报
使用Cloud Profiler进行性能分析
部署前使用模拟器进行本地测试

Recommended Tools

Common Pitfalls to Avoid

需避免的常见陷阱

Not using service accounts for workloads
Hardcoding project IDs or credentials
Ignoring cold start optimization for Cloud Functions
Not setting up proper IAM bindings
Missing Cloud Monitoring alerts
Over-provisioning resources
Not using VPC for sensitive workloads
Ignoring cost optimization best practices

不为工作负载使用服务账号
硬编码项目ID或凭证
忽略Cloud Functions的冷启动优化
未配置正确的IAM绑定
缺失Cloud Monitoring告警
过度配置资源
不为敏感工作负载使用VPC
忽略成本优化最佳实践