GraphQL Mutation 设计实战：从语义命名到乐观更新

type Mutation {
  updateUserProfile(input: UpdateUserProfileInput!): UpdateUserProfilePayload!
}

type UpdateUserProfilePayload {
  user: User!
  updatedFields: [String!]!   # 记录实际被更新的字段（可选）
}

# 推荐
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) { user { id } }
}

# 反模式：散参数随 mutation 数量爆炸
mutation CreateUser($email: String!, $password: String!, $nickname: String, ...) {
  createUser(email: $email, password: $password, nickname: $nickname) { ... }
}

input CreateUserInput {
  email: String!
  password: String!
  nickname: String!
  bio: String
}

input UpdateUserProfileInput {
  # 部分更新：所有字段可空，null 表示"不修改"
  nickname: String
  bio: String
  avatarUrl: String
}

import { gql, useMutation } from '@apollo/client';

const ADD_COMMENT = gql`
  mutation AddComment($input: AddCommentInput!) {
    addComment(input: $input) {
      comment { id content createdAt }
    }
  }
`;

function useAddComment() {
  const [addComment] = useMutation(ADD_COMMENT, {
    update(cache, { data }) {
      // 服务端返回后把真实 comment 写进缓存
      cache.modify({
        fields: {
          comments(existing = []) {
            return [...existing, data.addComment.comment];
          },
        },
      });
    },
    optimisticResponse: (variables) => ({
      addComment: {
        __typename: 'AddCommentPayload',
        comment: {
          __typename: 'Comment',
          id: `temp-${Date.now()}`,   // 临时 id，服务端返回后替换
          content: variables.input.content,
          createdAt: new Date().toISOString(),
        },
      },
    }),
  });
  return addComment;
}

# 服务端 Schema
scalar Upload

type Mutation {
  uploadAvatar(input: UploadAvatarInput!): UploadAvatarPayload!
}

input UploadAvatarInput {
  file: Upload!
  crop: CropInput
}

type UploadAvatarPayload {
  avatarUrl: String!
}

import { createUploadLink } from 'apollo-upload-client';

const link = createUploadLink({
  uri: '/graphql',
});

// 查询中使用变量承载 Upload 标量
const UPLOAD_AVATAR = gql`
  mutation UploadAvatar($file: Upload!) {
    uploadAvatar(input: { file: $file }) {
      avatarUrl
    }
  }
`;

// 触发上传：传 File 对象即可，link 会转成 multipart
await uploadAvatar({ variables: { file: fileInput.files[0] } });

// Apollo Server 4 + graphql-upload（需自行接入）
import { processRequest } from 'graphql-upload';

app.post('/graphql', (req, res, next) => {
  if (req.is('multipart/form-data')) {
    return processRequest(req, res)
      .then((body) => { req.body = body; next(); })
      .catch(next);
  }
  next();
});

input PayOrderInput {
  orderId: ID!
  clientMutationId: String!
}

type PayOrderPayload {
  order: Order!
  clientMutationId: String!
}

// 服务端：幂等键去重
async function payOrder(_root, args, ctx) {
  const { orderId, clientMutationId } = args.input;
  // 幂等键表（或 Redis SETNX）
  const ok = await ctx.redis.set(`idem:pay:${clientMutationId}`, '1', 'EX', 300, 'NX');
  if (!ok) {
    // 该键已处理过，直接返回上次结果
    const prev = await ctx.repo.getOrder(orderId);
    return { order: prev, clientMutationId };
  }
  // 正常执行业务
  const order = await ctx.paymentService.pay(orderId);
  return { order, clientMutationId };
}

input UpdateDocumentInput {
  documentId: ID!
  version: Int!          # 客户端持有的版本号
  title: String
  content: String
}

type UpdateDocumentPayload {
  document: Document!
  conflict: Boolean      # 是否发生版本冲突
}

async function updateDocument(_root, args, ctx) {
  const { documentId, version, ...patch } = args.input;
  // 原子条件更新：version 必须匹配
  const updated = await ctx.repo.updateDocumentWhere(
    { id: documentId, version },          // WHERE id=$1 AND version=$2
    { ...patch, version: version + 1 },   // 乐观锁 +1
  );
  if (!updated) {
    const current = await ctx.repo.getDocument(documentId);
    throw new GraphQLError('Document has been modified by another user', {
      extensions: { code: 'CONFLICT_VERSION_MISMATCH', currentVersion: current.version },
    });
  }
  return { document: updated, conflict: false };
}

import { PubSub } from 'graphql-subscriptions'; // 简单实现（仅单实例可用）

const pubsub = new PubSub();
const ORDER_CHANGED = 'ORDER_CHANGED';

// mutation 中发布事件
export const resolvers = {
  Mutation: {
    updateOrderStatus: async (_root, args, ctx) => {
      const order = await ctx.repo.updateOrderStatus(args.input);
      pubsub.publish(ORDER_CHANGED, {
        orderChanged: { orderId: order.id, status: order.status },
      });
      return { order };
    },
  },
  Subscription: {
    orderChanged: {
      // 订阅端可用过滤器缩小事件范围
      subscribe: (_root, args) => pubsub.asyncIterator(ORDER_CHANGED),
      resolve: (payload) => payload.orderChanged,
    },
  },
};

// Redis Pub/Sub 版
import { RedisPubSub } from 'graphql-redis-subscriptions';
import Redis from 'ioredis';

const pubsub = new RedisPubSub({
  publisher: new Redis(process.env.REDIS_URL!),
  subscriber: new Redis(process.env.REDIS_URL!),
});

// REST 409 Conflict → GraphQL extensions.code = CONFLICT_*
function mapRestStatusToError(status: number, body: any): GraphQLError {
  switch (status) {
    case 400: return new ValidationError(body.issues ?? []);
    case 401: return new GraphQLError('Unauthorized', { extensions: { code: 'UNAUTHORIZED' } });
    case 403: return new GraphQLError('Forbidden', { extensions: { code: 'FORBIDDEN' } });
    case 404: return new GraphQLError('Not found', { extensions: { code: 'NOT_FOUND' } });
    case 409: return new GraphQLError(body.message, { extensions: { code: 'CONFLICT_' + body.code } });
    default:  return new GraphQLError('Upstream error', { extensions: { code: 'UPSTREAM_ERROR' } });
  }
}

type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
  payOrder(input: PayOrderInput!): PayOrderPayload!
  cancelOrder(input: CancelOrderInput!): CancelOrderPayload!
  confirmReceipt(input: ConfirmReceiptInput!): ConfirmReceiptPayload!
}

input CreateOrderInput {
  items: [OrderItemInput!]!
  addressId: ID!
  couponCode: String
}

input PayOrderInput {
  orderId: ID!
  paymentMethod: PaymentMethod!
  clientMutationId: String!   # 幂等键
}