사용자 정의 코드 품질 규칙 custom-code-quality-rules

철저한 테스트를 통해 고품질 코드를 보장하기 위해 Adobe Experience Manager 엔지니어링 모범 사례를 기반으로 하는 Cloud Manager의 사용자 지정 코드 품질 규칙에 대해 알아봅니다. 코드 품질 테스트도 참조하세요.

SonarQube 규칙 sonarqube-rules

다음 섹션에서는 Cloud Manager에서 실행되는 SonarQube 규칙에 대해 자세히 설명합니다.

잠재적으로 위험한 기능을 사용하지 않음 do-not-use-potentially-dangerous-functions

Thread.stop() 및 Thread.interrupt() 메서드는 재현하기 어려운 문제와 경우에 따라 보안 취약성을 발생시킬 수 있습니다. 이러한 사용은 철저하게 모니터링되고 검증되어야 합니다. 일반적으로 메시지 전달은 유사한 목표를 달성하기 위한 보다 안전한 방법입니다.

비준수 코드 non-compliant-code

public class DontDoThis implements Runnable {
  private Thread thread;

  public void start() {
    thread = new Thread(this);
    thread.start();
  }

  public void stop() {
    thread.stop();  // UNSAFE!
  }

  public void run() {
    while (true) {
        somethingWhichTakesAWhileToDo();
    }
  }
}

준수 코드 compliant-code

public class DoThis implements Runnable {
  private Thread thread;
  private boolean keepGoing = true;

  public void start() {
    thread = new Thread(this);
    thread.start();
  }

  public void stop() {
    keepGoing = false;
  }

  public void run() {
    while (this.keepGoing) {
        somethingWhichTakesAWhileToDo();
    }
  }
}

외부에서 제어할 수 있는 형식 문자열을 사용하지 않음 do-not-use-format-strings-which-may-be-externally-controlled

외부 소스의 형식 문자열(예: 요청 매개변수 또는 사용자 생성 콘텐츠)을 사용하면 애플리케이션이 서비스 거부 공격에 노출될 수 있습니다. 형식 문자열이 외부에서 제어될 수 있지만 신뢰할 수 있는 소스에서만 허용되는 환경이 있습니다.

비준수 코드 non-compliant-code-1

protected void doPost(SlingHttpServletRequest request, SlingHttpServletResponse response) {
  String messageFormat = request.getParameter("messageFormat");
  request.getResource().getValueMap().put("some property", String.format(messageFormat, "some text"));
  response.sendStatus(HttpServletResponse.SC_OK);
}

HTTP 요청에 항상 소켓 및 연결 시간 초과가 포함되어 있어야 함 http-requests-should-always-have-socket-and-connect-timeouts

Experience Manager 애플리케이션 내에서 HTTP 요청을 할 때는 불필요한 스레드 소비를 방지하기 위해 적절한 시간 초과를 구성해야 합니다.
기본적으로 Java™ HTTP 클라이언트(java.net.HttpUrlConnection)와 널리 사용되는 Apache HTTP 구성 요소 클라이언트는 모두 시간 초과를 적용하지 않으므로 수동으로 구성해야 합니다. 시간 초과는 60초 이하로 설정하는 것이 좋습니다.

비준수 코드 non-compliant-code-2

@Reference
private HttpClientBuilderFactory httpClientBuilderFactory;

public void dontDoThis() {
  HttpClientBuilder builder = httpClientBuilderFactory.newBuilder();
  HttpClient httpClient = builder.build();

  // do something with the client
}

public void dontDoThisEither() {
  URL url = new URL("http://www.google.com");
  URLConnection urlConnection = url.openConnection();

  BufferedReader in = new BufferedReader(new InputStreamReader(
    urlConnection.getInputStream()));

  String inputLine;
  while ((inputLine = in.readLine()) != null) {
    logger.info(inputLine);
  }

  in.close();
}

준수 코드 compliant-code-1

@Reference
private HttpClientBuilderFactory httpClientBuilderFactory;

public void doThis() {
  HttpClientBuilder builder = httpClientBuilderFactory.newBuilder();
  RequestConfig requestConfig = RequestConfig.custom()
    .setConnectTimeout(5000)
    .setSocketTimeout(5000)
    .build();
  builder.setDefaultRequestConfig(requestConfig);

  HttpClient httpClient = builder.build();

  // do something with the client
}

public void orDoThis () {
  URL url = new URL("http://www.google.com");
  URLConnection urlConnection = url.openConnection();
  urlConnection.setConnectTimeout(5000);
  urlConnection.setReadTimeout(5000);

  BufferedReader in = new BufferedReader(new InputStreamReader(
    urlConnection.getInputStream()));

  String inputLine;
  while ((inputLine = in.readLine()) != null) {
    logger.info(inputLine);
  }

  in.close();
}

항상 ResourceResolver 오브젝트를 닫아야 함 resourceresolver-objects-should-always-be-closed

ResourceResolverFactory에서 가져온 ResourceResolver 개체는 시스템 리소스를 사용합니다. ResourceResolver가 더 이상 사용되지 않을 때 이러한 리소스를 회수하는 방법이 있지만 close() 메서드를 호출하여 열려 있는 ResourceResolver 오브젝트를 명시적으로 닫는 것이 더 효율적입니다.

일반적인 오해 중 하나는 기존 JCR 세션으로 만든 ResourceResolver 개체를 명시적으로 닫지 말아야 하거나 닫으면 JCR 세션에 영향을 준다는 것입니다. 이 정보는 올바르지 않습니다. ResourceResolver은(는) 더 이상 필요하지 않으면 항상 닫아야 합니다. ResourceResolver이(가) Closeable 인터페이스를 구현하므로 close()을(를) 직접 호출하는 대신 try-with-resources 구문을 사용할 수도 있습니다.

비준수 코드 non-compliant-code-4

public void dontDoThis(Session session) throws Exception {
  ResourceResolver resolver = factory.getResourceResolver(Collections.singletonMap("user.jcr.session", (Object)session));
  // do some stuff with the resolver
}

준수 코드 compliant-code-2

public void doThis(Session session) throws Exception {
  ResourceResolver resolver = null;
  try {
    resolver = factory.getResourceResolver(Collections.singletonMap("user.jcr.session", (Object)session));
    // do something with the resolver
  } finally {
    if (resolver != null) {
      resolver.close();
    }
  }
}

public void orDoThis(Session session) throws Exception {
  try (ResourceResolver resolver = factory.getResourceResolver(Collections.singletonMap("user.jcr.session", (Object) session))){
    // do something with the resolver
  }
}

Sling 서블릿 경로를 사용하여 서블릿을 등록하지 않음 do-not-use-sling-servlet-paths-to-register-servlets

슬링 설명서에 설명된 대로 경로별로 서블릿을 바인딩하는 것은 권장되지 않습니다. 경로 바인딩 서블릿은 표준 JCR 액세스 제어를 사용할 수 없으며, 결과적으로 엄격한 추가 보안이 요구됩니다. 경로 바인딩 서블릿을 사용하는 대신 저장소에 노드를 생성하고 리소스 유형별로 서블릿을 등록하는 것이 좋습니다.

비준수 코드 non-compliant-code-5

@Component(property = {
  "sling.servlet.paths=/apps/myco/endpoint"
})
public class DontDoThis extends SlingAllMethodsServlet {
 // implementation
}

발견된 예외를 기록하거나 표시하되 둘 다 해서는 안 됨 caught-exceptions-should-be-logged-or-thrown-but-not-both

일반적으로 예외는 정확히 한 번 기록해야 합니다. 예외를 여러 번 기록하면 혼동이 발생할 수 있습니다. 예외가 몇 번 발생했는지 불분명하기 때문이다. 이 효과로 이어지는 가장 일반적인 패턴은 발생한 예외를 로깅하고 throw하는 것입니다.

비준수 코드 non-compliant-code-6

public void dontDoThis() throws Exception {
  try {
    someOperation();
  } catch (Exception e) {
    logger.error("something went wrong", e);
    throw e;
  }
}

준수 코드 compliant-code-3

public void doThis() {
  try {
    someOperation();
  } catch (Exception e) {
    logger.error("something went wrong", e);
  }
}

public void orDoThis() throws MyCustomException {
  try {
    someOperation();
  } catch (Exception e) {
    throw new MyCustomException(e);
  }
}

Throw 문 바로 뒤에 Log 문을 사용하지 않음 avoid-having-a-log-statement-immediately-followed-by-a-throw-statement

피해야 할 또 다른 일반적인 패턴은 메시지를 기록한 다음 즉시 예외를 발생시키는 것입니다. 이러한 사례는 일반적으로 예외 메시지가 로그 파일에 중복됨을 나타냅니다.

비준수 코드 non-compliant-code-7

public void dontDoThis() throws Exception {
  logger.error("something went wrong");
  throw new RuntimeException("something went wrong");
}

준수 코드 compliant-code-4

public void doThis() throws Exception {
  throw new RuntimeException("something went wrong");
}

GET 또는 HEAD 요청을 처리할 때 INFO에서 로깅하지 않음 avoid-logging-at-info-when-handling-get-or-head-requests

일반적으로 INFO 로그 수준은 중요한 작업을 구분하는 데 사용되어야 하며 기본적으로 Experience Manager는 INFO 수준 또는 그 이상에서 기록되도록 구성됩니다. GET 및 HEAD 메서드는 읽기 전용 작업이어야 하므로 중요한 작업을 구성하지 않습니다. GET 또는 HEAD 요청에 대한 응답으로 INFO 수준에서 로깅하면 상당한 로그 노이즈가 발생하여 로그 파일에서 유용한 정보를 식별하기가 더 어려워질 수 있습니다. GET 또는 HEAD 요청을 처리할 때 문제가 발생하면 WARN 또는 ERROR 수준에서 기록합니다. 자세한 문제 해결 정보가 필요한 경우 디버그 또는 TRACE 수준을 사용합니다.

비준수 코드 non-compliant-code-8

public void doGet() throws Exception {
  logger.info("handling a request from the user");
}

준수 코드 compliant-code-5

public void doGet() throws Exception {
  logger.debug("handling a request from the user.");
}

Logging 문의 첫 번째 매개변수로 Exception.getMessage()를 사용하지 않음 do-not-use-exception-getmessage-as-the-first-parameter-of-a-logging-statement

가장 좋은 방법은 로그 메시지가 애플리케이션에서 예외가 발생한 위치에 대한 상황별 정보를 제공하는 것입니다. 스택 추적을 사용하여 컨텍스트를 결정할 수도 있지만 일반적으로 로그 메시지는 읽고 이해하는 것이 더 쉬울 것입니다. 따라서 예외를 기록할 때 예외 메시지를 로그 메시지로 사용하는 것은 잘못된 관행입니다. 예외 메시지는 무엇이 잘못되었는지 설명하지만, 로그 메시지는 예외 발생 시 애플리케이션이 무엇을 하고 있었는지에 대해 판독기에 알려주어야 합니다. 예외 메시지는 계속 기록됩니다. 고유한 메시지를 지정하면 로그를 쉽게 이해할 수 있습니다.

비준수 코드 non-compliant-code-9

public void dontDoThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.error(e.getMessage(), e);
  }
}

준수 코드 compliant-code-6

public void doThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.error("Unable to do something", e);
  }
}

Catch 블록에 로그인할 때 WARN 또는 ERROR 수준을 유지해야 함 logging-in-catch-blocks-should-be-at-the-warn-or-error-level

이름에서 알 수 있듯이 Java™ 예외는 예외적인 상황에서 항상 사용되어야 합니다. 결과적으로 예외가 발생하면 로그 메시지가 WARN 또는 ERROR 중 적절한 수준으로 기록되도록 하는 것이 중요합니다. 이 프로세스에서는 이러한 메시지가 로그에 올바르게 표시되는지 확인합니다.

비준수 코드 non-compliant-code-10

public void dontDoThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.debug(e.getMessage(), e);
  }
}

준수 코드 compliant-code-7

public void doThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.error("Unable to do something", e);
  }
}

콘솔에 스택 추적을 인쇄하지 않음 do-not-print-stack-traces-to-the-console

앞에서 언급했듯이 로그 메시지를 이해할 때는 컨텍스트가 중요합니다. Exception.printStackTrace()를 사용하면 스택 추적만 표준 오류 스트림으로 출력되므로 모든 컨텍스트가 손실됩니다. 또한 Experience Manager와 같은 다중 스레드 애플리케이션에서 이 방법을 사용하여 여러 예외를 병렬로 인쇄하면 스택 추적이 겹쳐서 상당한 혼동을 일으킬 수 있습니다. 예외는 로깅 프레임워크에서만 기록되어야 합니다.

비준수 코드 non-compliant-code-11

public void dontDoThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    e.printStackTrace();
  }
}

준수 코드 compliant-code-8

public void doThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.error("Unable to do something", e);
  }
}

표준 출력 또는 표준 오류로 출력하지 않음 do-not-output-to-standard-output-or-standard-error

Experience Manager에서의 로깅은 항상 로깅 프레임워크(SLF4J)를 통해 수행되어야 합니다. 표준 출력 또는 표준 오류 스트림으로 직접 출력하면 로깅 프레임워크에서 제공하는 구조 및 컨텍스트 정보가 손실될 수 있습니다. 그에 따라 성능 문제가 발생할 수도 있습니다.

비준수 코드 non-compliant-code-12

public void dontDoThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    System.err.println("Unable to do something");
  }
}

준수 코드 compliant-code-9

public void doThis() {
  try {
    someMethodThrowingAnException();
  } catch (Exception e) {
    logger.error("Unable to do something", e);
  }
}

하드 코딩된 앱 및 라이브러리 경로 방지 avoid-hardcoded-apps-and-libs-paths

/libs 및 /apps로 시작하는 경로는 일반적으로 하드코딩해서는 안 됩니다. 이러한 경로는 일반적으로 Sling 검색 경로를 기준으로 저장되며 기본값은 /libs,/apps입니다. 절대 경로를 사용하면 프로젝트 수명 주기의 후반에만 나타나는 미묘한 결함이 발생할 수 있습니다.

비준수 코드 non-compliant-code-13

public boolean dontDoThis(Resource resource) {
  return resource.isResourceType("/libs/foundation/components/text");
}

준수 코드 compliant-code-10

public void doThis(Resource resource) {
  return resource.isResourceType("foundation/components/text");
}

Sling 스케줄러를 사용하지 않음 sonarqube-sling-scheduler

보장된 실행이 필요한 작업에는 Sling 스케줄러를 사용하지 마십시오. Sling의 예정된 작업은 실행을 보장하며 클러스터된 환경과 클러스터되지 않은 환경 모두에 더 적합합니다.

클러스터된 환경에서 Sling 작업이 처리되는 방법에 대한 자세한 내용은 Apache Sling 이벤트 및 작업 처리를 참조하십시오.

더 이상 사용되지 않는 Experience Manager API를 사용하지 않음 sonarqube-aem-deprecated

Experience Manager API 영역은 사용이 권장되지 않아 더 이상 사용되지 않는 것으로 간주되는 API를 식별하기 위해 지속적으로 수정되고 있습니다.

대부분의 경우 이러한 API는 표준 Java™ @Deprecated 주석을 사용하여 더 이상 사용되지 않으며, squid:CallToDeprecatedMethod에 의해 식별됩니다.

그러나 Experience Manager의 컨텍스트에서는 API가 더 이상 사용되지 않지만 다른 컨텍스트에서는 사용되는 경우가 있습니다. 이 규칙은 이 두 번째 클래스를 식별합니다.

슬링 모델에서 @Inject과 함께 @Optional 주석 사용 안 함 sonarqube-slingmodels-inject-optional

Apache Sling 프로젝트는 DefaultInjectionStrategy.OPTIONAL(필드 또는 클래스 수준)과 결합할 때 성능이 저하될 수 있으므로 Sling 모델의 컨텍스트에서 @Inject 주석을 사용하지 못하도록 합니다. 대신 보다 구체적인 주입(예: @ValueMapValue 또는 @OsgiInjector 주석)을 사용해야 합니다.

권장 주석과 이 권장 사항이 처음에 만들어진 이유에 대한 자세한 내용은 Apache Sling 설명서를 참조하십시오.

HTTPClient 인스턴스 재사용 sonarqube-reuse-httpclient

AEM 애플리케이션은 종종 HTTP 프로토콜을 사용하여 다른 애플리케이션에 연결되는데, Apache HttpClient는 이를 위해 종종 사용되는 라이브러리입니다. 그러나 이러한 HttpClient 개체를 만들면 약간의 오버헤드가 발생하므로 이러한 개체를 가능한 한 재사용해야 합니다.

이 규칙은 이러한 HttpClient 개체가 메서드 내에서 private이 아니라 클래스 수준에서 전역적이므로 재사용할 수 있는지 확인합니다. 이 경우 클래스 또는 activate() 메서드의 생성자에서 HttpClient 필드를 설정해야 합니다(이 클래스가 OSGi 구성 요소/서비스인 경우).

HttpClient의 최적화 안내서에서 HttpClient 사용과 관련된 몇 가지 모범 사례를 확인하십시오.

비준수 코드 non-compliant-code-14

public void doHttpCall() {
  HttpClient httpclient = HttpClients.createDefault();
  // do something with the httpclient
}

준수 코드 compliant-code-11

public class myClass {

  HttpClient httpclient;

  public void doHttpCall() {
    // do something with the httpclient
  }

}

OakPAL 콘텐츠 규칙 oakpal-rules

다음 섹션에서는 Cloud Manager에서 실행되는 OakPAL 검사에 대해 자세히 설명합니다.

고객은 로 주석이 달린 제품 API를 구현하거나 확장해서는 안 됩니다@ProviderType product-apis-annotated-with-providertype-should-not-be-implemented-or-extended-by-customers

Experience Manager API에는 사용자 정의 코드에 의해 사용될 뿐 구현되지 않는 Java™ 인터페이스 및 클래스가 포함되어 있습니다. 예를 들어 Experience Manager만 com.day.cq.wcm.api.Page 인터페이스를 구현해야 합니다.

이러한 인터페이스에 새 메서드를 추가해도 추가된 메서드는 이러한 인터페이스를 사용하는 기존 코드에 영향을 주지 않습니다. 결과적으로 이러한 인터페이스에 새 메서드를 추가해도 이전 버전과 호환되는 것으로 간주됩니다. 그러나 사용자 정의 코드로 이러한 인터페이스 중 하나를 구현하는 경우 해당 사용자 정의 코드로 인해 이전 버전과 호환되지 않는 문제가 발생합니다.

Experience Manager에 의해 구현되도록 의도된 인터페이스와 클래스는 org.osgi.annotation.versioning.ProviderType 또는 경우에 따라 유사한 기존 주석 aQute.bnd.annotation.ProviderType으로 주석을 추가할 수 있습니다. 이 규칙은 사용자 지정 코드가 이러한 인터페이스를 구현하거나 클래스를 확장하는 경우를 식별합니다.

비준수 코드 non-compliant-code-3

import com.day.cq.wcm.api.Page;

public class DontDoThis implements Page {
// implementation here
}

사용자 정의 Lucene Oak 인덱스에 Tika 구성을 포함해야 함 oakpal-indextikanode

기본 제공되는 여러 Experience Manager Oak 인덱스에는 Tika 구성이 포함되며 이러한 인덱스의 사용자 정의 항목에는 Tika 구성이 포함되어야 합니다. 이 규칙은 damAssetLucene, lucene 및 graphqlConfig 인덱스의 사용자 정의 항목을 확인하고 tika 노드가 누락되거나 tika 노드에 config.xml이라는 하위 노드가 누락된 경우 문제를 발생시킵니다.

인덱스 정의 사용자 정의에 대한 자세한 내용은 인덱싱 설명서를 참조하십시오.

비준수 코드 non-compliant-code-indextikanode

+ oak:index
    + damAssetLucene-1-custom
      - async: [async]
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - tags: [visualSimilaritySearch]
      - type: lucene

준수 코드 compliant-code-indextikanode

+ oak:index
    + damAssetLucene-1-custom-2
      - async: [async]
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - tags: [visualSimilaritySearch]
      - type: lucene
      + tika
        + config.xml

사용자 정의 Lucene Oak 인덱스를 동기화하지 않음 oakpal-indexasync

lucene 유형의 Oak 인덱스는 항상 비동기식으로 인덱싱되어야 합니다. 이렇게 하지 않으면 시스템이 불안정해질 수 있습니다. Lucene 인덱스 구조에 대한 자세한 내용은 Oak 설명서를 참조하세요.

비준수 코드 non-compliant-code-indexasync

+ oak:index
    + damAssetLucene-1-custom
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - type: lucene
      - tags: [visualSimilaritySearch]
      + tika
        + config.xml

준수 코드 compliant-code-indexasync

+ oak:index
    + damAssetLucene-1-custom-2
      - async: [async]
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - tags: [visualSimilaritySearch]
      - type: lucene
      + tika
        + config.xml

사용자 정의 DAM Asset Lucene Oak 인덱스를 올바르게 구성해야 함 oakpal-damAssetLucene-sanity-check

Experience Manager Assets에서 에셋 검색이 올바르게 작동하려면 damAssetLucene Oak 인덱스의 사용자 정의가 이 인덱스와 관련된 일련의 지침을 따라야 합니다. 이 규칙은 인덱스 정의에 visualSimilaritySearch 값을 포함하는 tags(이)라는 다중 값 속성이 있어야 하는지 확인합니다.

비준수 코드 non-compliant-code-damAssetLucene

+ oak:index
    + damAssetLucene-1-custom
      - async: [async, nrt]
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - type: lucene
      + tika
        + config.xml

준수 코드 compliant-code-damAssetLucene

+ oak:index
    + damAssetLucene-1-custom-2
      - async: [async, nrt]
      - evaluatePathRestrictions: true
      - includedPaths: /content/dam
      - tags: [visualSimilaritySearch]
      - type: lucene
      + tika
        + config.xml

고객 패키지는 libs에서 노드를 생성하거나 수정해서는 안 됨 oakpal-customer-package

Experience Manager 콘텐츠 저장소의 /libs 콘텐츠 트리는 고객이 읽기 전용으로 간주해야 하는 것이 오랜 모범 사례였습니다. /libs에서 노드 및 속성을 수정하면 주 업데이트 및 부 업데이트에 상당한 위험이 발생합니다. 공식 채널을 통해 Adobe을 사용하여 /libs을(를) 수정하십시오.

패키지에 중복된 OSGi 구성을 포함하지 않음 oakpal-package-osgi

복잡한 프로젝트에서 발생하는 일반적인 문제는 동일한 OSGi 구성 요소가 여러 번 구성되는 경우입니다. 이러한 문제가 발생하면 인해 어떤 구성이 적용 가능할지 모호해집니다. 이 규칙은 동일한 구성 요소가 동일한 실행 모드 또는 실행 모드 조합에서 여러 번 구성된 문제만 식별한다는 점에서 “실행 모드 인식” 규칙입니다.

비준수 코드 non-compliant-code-osgi

+ apps
  + projectA
    + config
      + com.day.cq.commons.impl.ExternalizerImpl
  + projectB
    + config
      + com.day.cq.commons.impl.ExternalizerImpl

준수 코드 compliant-code-osgi

+ apps
  + shared-config
    + config
      + com.day.cq.commons.impl.ExternalizerImpl

구성 및 설치 폴더에 OSGi 노드만 포함해야 함 oakpal-config-install

보안상의 이유로 /config/ 및 /install/가 포함된 경로는 Experience Manager의 관리 사용자만 읽을 수 있으며 OSGi 구성 및 OSGi 번들에만 사용해야 합니다. 이러한 세그먼트를 포함하는 경로에 다른 유형의 콘텐츠를 배치하면 관리 사용자와 비관리 사용자 간에 의도하지 않게 애플리케이션 동작이 달라집니다.

일반적인 문제는 구성 요소 대화 상자 내에서 config라는 노드를 사용하거나 인라인 편집을 위해 리치 텍스트 편집기 구성을 지정할 때 발생합니다. 이 문제를 해결하려면 문제가 있는 노드의 이름을 규정 준수 이름으로 변경해야 합니다. 리치 텍스트 편집기 구성의 경우 cq:inplaceEditing 노드의 configPath 속성을 사용하여 새 위치를 지정하십시오.

비준수 코드 non-compliant-code-config-install

+ cq:editConfig [cq:EditConfig]
  + cq:inplaceEditing [cq:InplaceEditConfig]
    + config [nt:unstructured]
      + rtePlugins [nt:unstructured]

준수 코드 compliant-code-config-install

+ cq:editConfig [cq:EditConfig]
  + cq:inplaceEditing [cq:InplaceEditConfig]
    ./configPath = inplaceEditingConfig (String)
    + inplaceEditingConfig [nt:unstructured]
      + rtePlugins [nt:unstructured]

패키지를 겹치지 않음 oakpal-no-overlap

패키지에 중복된 OSGi 구성 규칙을 포함해서는 안 됨과 마찬가지로, 여러 개의 개별 콘텐츠 패키지에 의해 동일한 노드 경로가 기록되는 복잡한 프로젝트에서 일반적인 문제입니다. 콘텐츠 패키지 종속성을 사용하면 일관된 결과를 보장할 수 있지만 중복을 완전히 피하는 것이 좋습니다.

기본 작성 모드는 클래식 UI가 아니어야 합니다. oakpal-default-authoring

com.day.cq.wcm.core.impl.AuthoringUIModeServiceImpl OSGi 구성은 Experience Manager 내의 기본 작성 모드를 정의합니다. Experience Manager 6.4 이후 Classic UI가 더 이상 사용되지 않으므로 기본 작성 모드가 Classic UI로 구성되면 문제가 발생합니다.

대화 상자가 있는 구성 요소에는 터치 UI 대화 상자가 있어야 함 oakpal-components-dialogs

클래식 UI 대화 상자가 있는 Experience Manager 구성 요소에는 항상 해당 터치 UI 대화 상자가 있어야 합니다. 둘 다 클래식 UI가 더 이상 지원되지 않는 Cloud Service 배포 모델과 호환되는 최적의 작성 환경을 제공합니다. 이 규칙은 다음 시나리오를 확인합니다.

Experience Manager 현대화 도구 설명서는 구성 요소를 Classic UI에서 Touch UI로 변환하는 방법에 대한 문서와 도구를 제공합니다. 자세한 내용은 Experience Manager 현대화 도구 설명서를 참조하십시오.

패키지에 변경 가능한 콘텐츠 및 변경 불가능한 콘텐츠를 혼합하지 않음 oakpal-packages-immutable

Cloud Service 배포 모델과 호환되려면 개별 콘텐츠 패키지에 저장소의 변경 불가능한 영역(/apps 및 /libs) 또는 변경 가능한 영역(/apps 또는 /libs에 있지 않은 모든 것)에 대한 콘텐츠가 포함되어 있어야 하지만 둘 다 포함되어서는 안 됩니다. 예를 들어 /apps/myco/components/text과(와) /etc/clientlibs/myco이(가) 모두 포함된 패키지는 Cloud Service과 호환되지 않으므로 문제가 보고됩니다.

자세한 내용은 Experience Manager 프로젝트 구조 설명서를 참조하십시오.

역방향 복제 에이전트를 사용하지 않음 oakpal-reverse-replication

Experience Manager as a Cloud Service의 릴리스 정보에서 설명한 대로 Cloud Service 배포에서는 역방향 복제에 대한 지원을 사용할 수 없습니다.

역방향 복제를 사용하는 고객은 Adobe에 대체 솔루션을 문의해야 합니다.

프록시가 활성화된 클라이언트 라이브러리에 포함된 리소스는 “resources” 폴더에 있어야 함 oakpal-resources-proxy

Experience Manager 클라이언트 라이브러리에는 이미지 및 글꼴과 같은 정적 리소스가 포함될 수 있습니다. 문서 프로세서 사용에 설명된 대로 프록시 클라이언트 라이브러리를 사용할 때 게시 인스턴스에서 효과적으로 참조하려면 이러한 정적 리소스가 resources이라는 하위 폴더에 포함되어 있어야 합니다.

비준수 코드 non-compliant-proxy-enabled

+ apps
  + projectA
    + clientlib
      - allowProxy=true
      + images
        + myimage.jpg

준수 코드 compliant-proxy-enabled

+ apps
  + projectA
    + clientlib
      - allowProxy=true
      + resources
        + myimage.jpg

Cloud Service의 호환되지 않는 워크플로 프로세스 사용 oakpal-usage-cloud-service

Adobe Experience Manager as a Cloud Service의 에셋 처리를 위해 에셋 마이크로 서비스로 이동하면서, 이제 온-프레미스 및 AMS 버전에서 사용되는 여러 워크플로 프로세스가 지원되지 않습니다. 이러한 많은 워크플로우가 불필요하게 되었습니다.

Experience Manager as a Cloud Service Assets GitHub 저장소에 있는 마이그레이션 도구를 사용하여 Experience Manager as a Cloud Service로 마이그레이션하는 동안 워크플로 모델을 업데이트할 수 있습니다.

편집 가능한 템플릿을 위해 정적 템플릿을 사용하지 않음 oakpal-static-template

이전까지는 Experience Manager 프로젝트에서 정적 템플릿을 매우 흔히 사용했지만 이제는 가장 유연하고 정적 템플릿에 없는 추가 기능을 지원하는 편집 가능한 템플릿을 사용하는 것이 좋습니다. 자세한 내용은 페이지 템플릿 문서에서 확인할 수 있습니다.

정적 템플릿에서 편집 가능한 템플릿으로의 마이그레이션은 Experience Manager 현대화 도구를 사용하여 대부분 자동화할 수 있습니다.

기존 기초 구성 요소를 사용하지 않음 oakpal-usage-legacy

기존 기초 구성 요소(예: /libs/foundation 아래의 구성 요소)는 핵심 구성 요소를 위한 여러 Experience Manager 릴리스에서 더 이상 사용되지 않습니다. 오버레이 또는 상속 여부에 관계없이 기존 기초 구성 요소를 사용자 정의 구성 요소의 기반으로 사용하는 것은 권장되지 않으며 해당 핵심 구성 요소로 변환해야 합니다.

Experience Manager 현대화 도구를 통해 이 변환을 용이하게 할 수 있습니다.

지원되는 실행 모드 이름 및 순서만 사용해야 함 oakpal-supported-runmodes

Experience Manager as a Cloud Service는 실행 모드 이름에 대해 엄격한 이름 지정 정책을 시행하고 해당 실행 모드에 대해 엄격한 순서를 적용합니다. 지원되는 실행 모드 목록은 Experience Manageras a Cloud Service 에 배포 문서에 있으며, 이 목록과 다른 모든 편차는 문제로 식별됩니다.

사용자 정의 검색 인덱스 정의 노드는 /oak:index의 직접 하위 노드여야 함 oakpal-custom-search

Experience Manager as a Cloud Service를 사용하려면 사용자 정의 검색 인덱스 정의(예: oak:QueryIndexDefinition 유형의 노드)가 /oak:index의 직접 하위 노드여야 합니다. Experience Manager as a Cloud Service와 호환되려면 다른 위치의 인덱스를 이동해야 합니다. 검색 인덱스에 대한 자세한 내용은 콘텐츠 검색 및 색인화 문서를 참조하십시오.

사용자 정의 검색 인덱스 정의 노드의 compatVersion을 2로 설정해야 함 oakpal-custom-search-compatVersion

Experience Manager as a Cloud Service를 사용하려면 사용자 정의 검색 인덱스 정의(예: oak:QueryIndexDefinition 유형의 노드)에 2로 설정된 compatVersion 속성이 있어야 합니다. Adobe Experience Manager as a Cloud Service은 다른 값을 지원하지 않습니다. 검색 인덱스에 대한 자세한 내용은 콘텐츠 검색 및 색인화를 참조하십시오.

사용자 정의 검색 인덱스 정의 노드의 하위 노드 유형은 nt:unstructured 여야 함 oakpal-descendent-nodes

사용자 정의 검색 인덱스 정의 노드에 순서가 지정되지 않은 하위 노드가 있으면 문제를 해결하기 어려운 문제가 발생할 수 있습니다. 이러한 상황을 방지하려면 oak:QueryIndexDefinition 노드의 모든 하위 노드가 nt:unstructured 유형인 것이 좋습니다.

사용자 정의 검색 인덱스 정의 노드에 하위 노드가 있는 “indexRules” 하위 노드를 포함해야 함 oakpal-custom-search-index

올바르게 정의된 사용자 정의 검색 인덱스 정의 노드에는 indexRules(이)라는 하위 노드가 있어야 하며, 이 노드에는 하나 이상의 하위 노드가 있어야 합니다. 자세한 내용은 Oak 문서에서 확인할 수 있습니다.

사용자 정의 검색 인덱스 정의 노드는 명명 규칙을 준수해야 함 oakpal-custom-search-definitions

Experience Manager as a Cloud Service를 사용하려면 사용자 정의 검색 인덱스 정의(예: oak:QueryIndexDefinition 유형의 노드)를 콘텐츠 검색 및 색인화 문서에 설명된 특정 패턴에 따라 지정해야 합니다.

사용자 정의 검색 인덱스 정의 노드는 lucene 유형의 인덱스를 사용해야 함 oakpal-index-type-lucene

Experience Manager as a Cloud Service를 사용하려면 사용자 정의 검색 인덱스 정의(예: oak:QueryIndexDefinition 유형의 노드)에 값이 lucene으로 설정된 type 속성이 있어야 합니다. 기존 인덱스 유형을 사용하는 색인화는 Experience Manager as a Cloud Service로 마이그레이션하기 전에 업데이트해야 합니다. 자세한 내용은 콘텐츠 검색 및 색인화를 참조하십시오.

사용자 정의 검색 인덱스 정의 노드에 “seed” 속성을 포함하지 않음 oakpal-property-name-seed

Experience Manager as a Cloud Service에서는 사용자 정의 검색 인덱스 정의(즉, oak:QueryIndexDefinition 유형의 노드)에 seed라는 속성을 포함할 수 없습니다. 이 속성을 사용하는 색인화는 Experience Manager as a Cloud Service로 마이그레이션하기 전에 업데이트해야 합니다. 자세한 내용은 콘텐츠 검색 및 색인화 문서를 참조하십시오.

사용자 정의 검색 인덱스 정의 노드에 “reindex” 속성을 포함하지 않음 oakpal-reindex-property

Experience Manager as a Cloud Service에서는 사용자 정의 검색 인덱스 정의(즉, oak:QueryIndexDefinition 유형의 노드)에 reindex라는 속성을 포함할 수 없습니다. 이 속성을 사용하는 색인화는 Experience Manager 로 마이그레이션하기 전에 업데이트해야 합니다.
Cloud Service. 자세한 내용은 콘텐츠 검색 및 색인화 문서를 참조하십시오.

사용자 지정 DAM 자산 Lucene 노드는 queryPaths을(를) 지정하지 않아야 합니다. oakpal-damAssetLucene-queryPaths

비준수 코드 non-compliant-code-damAssetLucene-queryPaths

+ oak:index
    + damAssetLucene-1-custom-1
      - async: [async, nrt]
      - evaluatePathRestrictions: true
      - includedPaths: [/content/dam]
      - queryPaths: [/content/dam]
      - type: lucene
      + tika
        + config.xml

준수 코드 compliant-code-damAssetLucene-queryPaths

+ oak:index
    + damAssetLucene-1-custom-2
      - async: [async, nrt]
      - evaluatePathRestrictions: true
      - includedPaths: [/content/dam]
      - tags: [visualSimilaritySearch]
      - type: lucene
      + tika
        + config.xml

사용자 지정 검색 인덱스 정의에 compatVersion이(가) 포함된 경우 2로 설정해야 합니다. oakpal-compatVersion

includedPaths을(를) 지정하는 인덱스 노드는 같은 값으로 queryPaths도 지정해야 합니다. oakpal-included-paths-without-query-paths

사용자 지정 인덱스의 경우 동일한 값으로 includedPaths 및 queryPaths을(를) 구성하십시오. 하나가 지정된 경우 다른 하나가 일치해야 합니다. 그러나 사용자 지정 버전을 포함하여 damAssetLucene의 인덱스에 대한 특별한 경우가 있습니다. 이러한 경우 includedPaths만 제공하십시오.

일반 노드 형식에 nodeScopeIndex을(를) 지정하는 인덱스 노드는 includedPaths 및 queryPaths도 지정해야 합니다. oakpal-full-text-on-generic-node-type

nt:unstructured 또는 nt:base과(와) 같은 "일반" 노드 형식에 대해 nodeScopeIndex 속성을 설정할 때는 includedPaths 및 queryPaths 속성도 지정해야 합니다.
노드 형식 nt:base은(는) "일반"으로 간주할 수 있습니다. 모든 노드 형식은 이 형식에서 상속되기 때문입니다. 따라서 nt:base에서 nodeScopeIndex을(를) 설정하면 저장소의 모든 노드를 인덱싱합니다. 마찬가지로 저장소에 이 형식의 노드가 많으므로 nt:unstructured도 "일반"으로 간주됩니다.

비준수 코드 non-compliant-code-full-text-on-generic-node-type

+ oak:index/acme.someIndex-custom-1
  - async: [async, nrt]
  - evaluatePathRestrictions: true
  - tags: [visualSimilaritySearch]
  - type: lucene
    + indexRules
      - jcr:primaryType: nt:unstructured
      + nt:base
        - jcr:primaryType: nt:unstructured
        + properties
          + acme.someIndex-custom-1
            - nodeScopeIndex: true

준수 코드 compliant-code-full-text-on-generic-node-type

+ oak:index/acme.someIndex-custom-1
  - async: [async, nrt]
  - evaluatePathRestrictions: true
  - tags: [visualSimilaritySearch]
  - type: lucene
  - includedPaths: ["/content/dam/"]
  - queryPaths: ["/content/dam/"]
    + indexRules
      - jcr:primaryType: nt:unstructured
      + nt:base
        - jcr:primaryType: nt:unstructured
        + properties
          + acme.someIndex-custom-1
            - nodeScopeIndex: true

쿼리 엔진의 queryLimitReads 속성을 재정의하면 안 됩니다. oakpal-query-limit-reads

기본값을 재정의하면 특히 더 많은 콘텐츠가 추가될 때 페이지 읽기 속도가 느려질 수 있습니다.

동일한 색인의 여러 활성 버전 oakpal-multiple-active-versions

비준수 코드 non-compliant-code-multiple-active-versions

+ oak:index
  + damAssetLucene-1-custom-1
    ...
  + damAssetLucene-1-custom-2
    ...
  + damAssetLucene-1-custom-3
    ...

준수 코드 compliant-code-multiple-active-versions

+ damAssetLucene-1-custom-3
    ...

완전히 맞춤화된 색인 정의의 이름은 공식 지침을 준수해야 합니다 oakpal-fully-custom-index-name

전체 사용자 지정 인덱스 이름에 필요한 패턴은 [prefix].[indexName]-custom-[version]입니다. 자세한 내용은 콘텐츠 검색 및 색인화 문서에서 확인할 수 있습니다.

동일한 색인 정의에서 다른 분석 값을 가진 동일한 속성 oakpal-same-property-different-analyzed-values

비준수 코드 non-compliant-code-same-property-different-analyzed-values

+ indexRules
  + dam:Asset
    + properties
      + status
        - name: status
        - analyzed: true
  + dam:cfVariationNode
    + properties
      + status
        - name: status

준수 코드 compliant-code-same-property-different-analyzed-values

예:

+ indexRules
  + dam:Asset
    + properties
      + status
        - name: status
        - analyzed: true
  + dam:cfVariationNode
    + properties
      + status
        - name: status
        - analyzed: true

예:

+ indexRules
  + dam:Asset
    + properties
      + status
        - name: status
  + dam:cfVariationNode
    + properties
      + status
        - name: status
        - analyzed: true

분석된 속성이 명시적으로 설정되지 않은 경우 기본값은 false입니다.

태그 속성 tags-property

특정 인덱스의 경우 태그 속성과 현재 값을 유지해야 합니다. 태그 속성에 새 값을 추가하는 것은 가능하지만, 기존 값(또는 속성을 모두 삭제)을 삭제하면 예기치 않은 결과가 발생할 수 있습니다.

UI 콘텐츠 패키지에 색인 정의 노드를 배포하면 안 됨 oakpal-ui-content-package

AEM Cloud Service는 UI 콘텐츠 패키지에 사용자 정의 검색 색인 정의(유형 oak:QueryIndexDefinition의 노드)를 배포할 수 없도록 합니다.

damAssetLucene 유형의 사용자 정의 전체 텍스트 인덱스 정의에 'damAssetLucene' 접두사가 올바르게 있어야 합니다. oakpal-dam-asset-lucene

AEM Cloud Service는 damAssetLucene의 사용자 정의 전체 텍스트 색인 정의에 damAssetLucene 이외의 접두사가 붙지 못하도록 합니다.

색인 정의 노드에는 동일한 이름의 속성이 포함되면 안 됨 oakpal-index-property-name

AEM Cloud Service는 사용자 정의 검색 색인 정의(즉, 유형 oak:QueryIndexDefinition의 노드)에 동일한 이름의 속성을 포함하는 것을 금지합니다.

특정 기본 제공 색인 정의는 사용자 정의할 수 없음 oakpal-customizing-ootb-index

AEM Cloud Service는 다음 OOTB 색인의 무단 수정을 금지합니다.

분석기의 토큰라이저 구성은 '토큰라이저'라는 이름으로 만들어야 합니다. oakpal-tokenizer

AEM Cloud Service에서는 분석기에서 이름이 잘못된 토큰라이저를 만들 수 없습니다. 토큰화는 항상 tokenizer로 정의되어야 합니다.

색인화 정의 구성에 공백이 포함되어서는 안 됨 oakpal-indexing-definitions-spaces

AEM Cloud Service는 공백이 있는 속성을 포함하는 색인화 ​​정의 생성을 금지합니다.