Xcode中Apollo-iOS未声明类型GraphQLMappable错误排查与配置

Hey there! Let's troubleshoot those "undeclared type" errors you're seeing with Apollo iOS—these usually stem from missing code generation steps, incorrect framework linking, or version mismatches. Here's a step-by-step breakdown to diagnose and fix the issue, plus a full correct setup guide:

First: Troubleshoot Your Current Error #

Let's narrow down why GraphQLMappable, GraphQLResultReader, and GraphQLNamedFragment aren't being recognized:

• Check Apollo Version Compatibility: Some older protocols like GraphQLMappable were deprecated or renamed in newer Apollo iOS versions (e.g., 2.x+). Double-check your Podfile to see which version you're using. If you're on 2.x+, you might need to adjust your code to use newer conventions like auto-generated model conformances instead of manually referencing these old types.
• Verify Code Generation Ran: Most of these types are either generated by Apollo's codegen tool or tied to generated API files. If you haven't run the code generator, or if it failed, those types won't exist. Check your generated API directory—are there Swift files there corresponding to your GraphQL queries/fragments?
• Confirm Import Statements: Make sure you're importing Apollo in every file that uses these types. If you're using generated fragments/queries, also ensure you're importing the generated API module (e.g., import GeneratedAPI if that's your output module name).
• Check Framework Linking: Head to your target's General > Frameworks, Libraries, and Embedded Content tab. Ensure Apollo is listed here, and set to Embed & Sign. If it's missing, re-run pod install and add it manually.
• Clean Xcode Cache: Sometimes stale build cache causes false errors. Try Cmd+Shift+K to clean the build folder, then restart Xcode and rebuild your project.

Full Correct Setup for Apollo iOS in Xcode #

If you need to reset your setup, follow these steps to get everything configured properly:

1. Install Apollo via CocoaPods #

First, make sure you're using the .xcworkspace file (not .xcodeproj) after setting up pods.

• Create/Update your Podfile with:

  platform :ios, '14.0' # Match your app's minimum iOS version
  target 'YourAppTargetName' do
    use_frameworks!
    pod 'Apollo'
    # Add pod 'Apollo/SQLite' if you need local caching
  end
  

• Run pod install in your project root directory.

2. Configure Apollo Code Generation #

This is the most critical step—without it, your custom GraphQL types won't be generated.

1. Create an apollo-codegen-config.json file in your project root:

   {
     "schemaPath": "./schema.graphqls", // Path to your downloaded GraphQL schema
     "outputPath": "./YourApp/GeneratedAPI/", // Folder where generated Swift code goes
     "includes": ["./YourApp/**/*.graphql"], // Path to your .graphql query/fragment files
     "excludes": []
   }
   

2. Add a Run Script Phase to your target:
   • Go to your target > Build Phases > Click the + button > New Run Script Phase
   • Drag this script above the Compile Sources phase
   • Paste this script (adjust paths to match your project):

     "${PODS_ROOT}/Apollo/scripts/run-bundled-codegen.sh" generate --target=swift --output-path="${SRCROOT}/YourApp/GeneratedAPI/" "${SRCROOT}/YourApp/**/*.graphql" --schema-path="${SRCROOT}/schema.graphqls"
     

3. Prepare Your GraphQL Schema and Queries #

• Download Your Schema: Use Apollo's CLI or your server's introspection endpoint to get your schema.graphqls file. Save it to the path you specified in the config.
• Create .graphql Files: Write your queries, mutations, and fragments in .graphql files (e.g., UserQueries.graphql). For example:

  fragment UserDetails on User {
    id
    name
    email
  }
  
  query GetUser($userId: ID!) {
    user(id: $userId) {
      ...UserDetails
    }
  }
  

4. Verify Import and Usage #

• In any Swift file using Apollo, import the framework and generated API:

  import Apollo
  import GeneratedAPI // Match your output module name
  

• Use the generated types instead of manually referencing GraphQLMappable—for example, the UserDetails fragment will have an auto-generated UserDetails struct that conforms to all necessary protocols.

5. Final Checks #

• Ensure all generated Swift files are included in Compile Sources (the run script should add them automatically, but double-check in Build Phases).
• Confirm your target's Build Settings > Swift Compiler - Search Paths includes the path to your generated API folder if needed.

内容的提问来源于stack exchange，提问作者mibbit